<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        
        <title>
            
    
                Column and Data Types
             &mdash; 
    SQLAlchemy 0.8 Documentation

        </title>
        
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="../_static/docs.css" type="text/css" />

    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
          URL_ROOT:    '../',
          VERSION:     '0.8.2',
          COLLAPSE_MODINDEX: false,
          FILE_SUFFIX: '.html'
      };
    </script>
        <script type="text/javascript" src="../_static/jquery.js"></script>
        <script type="text/javascript" src="../_static/underscore.js"></script>
        <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/init.js"></script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
        <link rel="copyright" title="Copyright" href="../copyright.html" />
    <link rel="top" title="SQLAlchemy 0.8 Documentation" href="../index.html" />
        <link rel="up" title="SQLAlchemy Core" href="index.html" />
        <link rel="next" title="Events" href="event.html" />
        <link rel="prev" title="Schema Definition Language" href="schema.html" />

    </head>
    <body>
        










<div id="docs-container">



<div id="docs-header">
    <h1>SQLAlchemy 0.8 Documentation</h1>

    <div id="docs-search">
    Search:
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" size="18" /> <input type="submit" value="Search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>

    <div id="docs-version-header">
        Release: <span class="version-num">0.8.2</span> | Release Date: July 3, 2013


    </div>

</div>

<div id="docs-top-navigation">
    <div id="docs-top-page-control" class="docs-navigation-links">
        <ul>
            <li>Prev:
            <a href="schema.html" title="previous chapter">Schema Definition Language</a>
            </li>
            <li>Next:
            <a href="event.html" title="next chapter">Events</a>
            </li>

        <li>
            <a href="../contents.html">Table of Contents</a> |
            <a href="../genindex.html">Index</a>
            | <a href="../_sources/core/types.txt">view source
        </li>
        </ul>
    </div>

    <div id="docs-navigation-banner">
        <a href="../index.html">SQLAlchemy 0.8 Documentation</a>
                » <a href="index.html" title="SQLAlchemy Core">SQLAlchemy Core</a>
        » 
                Column and Data Types
             

        <h2>
            
                Column and Data Types
            
        </h2>
    </div>

</div>

<div id="docs-body-container">

    <div id="docs-sidebar">
    <h3><a href="../index.html">Table of Contents</a></h3>
    <ul>
<li><a class="reference internal" href="#">Column and Data Types</a><ul>
<li><a class="reference internal" href="#generic-types">Generic Types</a></li>
<li><a class="reference internal" href="#sql-standard-types">SQL Standard Types</a></li>
<li><a class="reference internal" href="#vendor-specific-types">Vendor-Specific Types</a></li>
<li><a class="reference internal" href="#custom-types">Custom Types</a><ul>
<li><a class="reference internal" href="#overriding-type-compilation">Overriding Type Compilation</a></li>
<li><a class="reference internal" href="#augmenting-existing-types">Augmenting Existing Types</a></li>
<li><a class="reference internal" href="#typedecorator-recipes">TypeDecorator Recipes</a><ul>
<li><a class="reference internal" href="#coercing-encoded-strings-to-unicode">Coercing Encoded Strings to Unicode</a></li>
<li><a class="reference internal" href="#rounding-numerics">Rounding Numerics</a></li>
<li><a class="reference internal" href="#backend-agnostic-guid-type">Backend-agnostic GUID Type</a></li>
<li><a class="reference internal" href="#marshal-json-strings">Marshal JSON Strings</a></li>
</ul>
</li>
<li><a class="reference internal" href="#replacing-the-bind-result-processing-of-existing-types">Replacing the Bind/Result Processing of Existing Types</a></li>
<li><a class="reference internal" href="#applying-sql-level-bind-result-processing">Applying SQL-level Bind/Result Processing</a></li>
<li><a class="reference internal" href="#redefining-and-creating-new-operators">Redefining and Creating New Operators</a></li>
<li><a class="reference internal" href="#creating-new-types">Creating New Types</a></li>
</ul>
</li>
<li><a class="reference internal" href="#base-type-api">Base Type API</a></li>
</ul>
</li>
</ul>


    <h4>Previous Topic</h4>
    <p>
    <a href="schema.html" title="previous chapter">Schema Definition Language</a>
    </p>
    <h4>Next Topic</h4>
    <p>
    <a href="event.html" title="next chapter">Events</a>
    </p>


    <h4>Quick Search</h4>
    <p>
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" size="18" /> <input type="submit" value="Search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </p>

    </div>

    <div id="docs-body" class="withsidebar" >
        
<div class="section" id="module-sqlalchemy.types">
<span id="column-and-data-types"></span><span id="types-toplevel"></span><h1>Column and Data Types<a class="headerlink" href="#module-sqlalchemy.types" title="Permalink to this headline">¶</a></h1>
<p>SQLAlchemy provides abstractions for most common database data types,
and a mechanism for specifying your own custom data types.</p>
<p>The methods and attributes of type objects are rarely used directly.
Type objects are supplied to <tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt> definitions
and can be supplied as type hints to <cite>functions</cite> for occasions where
the database driver returns an incorrect type.</p>
<div class="highlight-pycon"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">users</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s">&#39;users&#39;</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span>
<span class="gp">... </span>              <span class="n">Column</span><span class="p">(</span><span class="s">&#39;id&#39;</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="gp">... </span>              <span class="n">Column</span><span class="p">(</span><span class="s">&#39;login&#39;</span><span class="p">,</span> <span class="n">String</span><span class="p">(</span><span class="mi">32</span><span class="p">))</span>
<span class="gp">... </span>             <span class="p">)</span></pre></div>
</div>
<p>SQLAlchemy will use the <tt class="docutils literal"><span class="pre">Integer</span></tt> and <tt class="docutils literal"><span class="pre">String(32)</span></tt> type
information when issuing a <tt class="docutils literal"><span class="pre">CREATE</span> <span class="pre">TABLE</span></tt> statement and will use it
again when reading back rows <tt class="docutils literal"><span class="pre">SELECTed</span></tt> from the database.
Functions that accept a type (such as <tt class="xref py py-func docutils literal"><span class="pre">Column()</span></tt>) will
typically accept a type class or instance; <tt class="docutils literal"><span class="pre">Integer</span></tt> is equivalent
to <tt class="docutils literal"><span class="pre">Integer()</span></tt> with no construction arguments in this case.</p>
<div class="section" id="generic-types">
<span id="types-generic"></span><h2>Generic Types<a class="headerlink" href="#generic-types" title="Permalink to this headline">¶</a></h2>
<p>Generic types specify a column that can read, write and store a
particular type of Python data.  SQLAlchemy will choose the best
database column type available on the target database when issuing a
<tt class="docutils literal"><span class="pre">CREATE</span> <span class="pre">TABLE</span></tt> statement.  For complete control over which column
type is emitted in <tt class="docutils literal"><span class="pre">CREATE</span> <span class="pre">TABLE</span></tt>, such as <tt class="docutils literal"><span class="pre">VARCHAR</span></tt> see <a class="reference internal" href="#sql-standard-types">SQL
Standard Types</a> and the other sections of this chapter.</p>
<dl class="class">
<dt id="sqlalchemy.types.BigInteger">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">BigInteger</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.BigInteger" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.Integer" title="sqlalchemy.types.Integer"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.Integer</span></tt></a></p>
<p>A type for bigger <tt class="docutils literal"><span class="pre">int</span></tt> integers.</p>
<p>Typically generates a <tt class="docutils literal"><span class="pre">BIGINT</span></tt> in DDL, and otherwise acts like
a normal <a class="reference internal" href="#sqlalchemy.types.Integer" title="sqlalchemy.types.Integer"><tt class="xref py py-class docutils literal"><span class="pre">Integer</span></tt></a> on the Python side.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.Boolean">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">Boolean</tt><big>(</big><em>create_constraint=True</em>, <em>name=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.Boolean" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.TypeEngine</span></tt></a>, <a class="reference internal" href="#sqlalchemy.types.SchemaType" title="sqlalchemy.types.SchemaType"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.SchemaType</span></tt></a></p>
<p>A bool datatype.</p>
<p>Boolean typically uses BOOLEAN or SMALLINT on the DDL side, and on
the Python side deals in <tt class="docutils literal"><span class="pre">True</span></tt> or <tt class="docutils literal"><span class="pre">False</span></tt>.</p>
<dl class="method">
<dt id="sqlalchemy.types.Boolean.__init__">
<tt class="descname">__init__</tt><big>(</big><em>create_constraint=True</em>, <em>name=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.Boolean.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a Boolean.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>create_constraint</strong> &#8211; defaults to True.  If the boolean
is generated as an int/smallint, also create a CHECK constraint
on the table that ensures 1 or 0 as a value.</li>
<li><strong>name</strong> &#8211; if a CHECK constraint is generated, specify
the name of the constraint.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.Date">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">Date</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.Date" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types._DateAffinity</span></tt>, <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.TypeEngine</span></tt></a></p>
<p>A type for <tt class="docutils literal"><span class="pre">datetime.date()</span></tt> objects.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.DateTime">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">DateTime</tt><big>(</big><em>timezone=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.DateTime" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types._DateAffinity</span></tt>, <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.TypeEngine</span></tt></a></p>
<p>A type for <tt class="docutils literal"><span class="pre">datetime.datetime()</span></tt> objects.</p>
<p>Date and time types return objects from the Python <tt class="docutils literal"><span class="pre">datetime</span></tt>
module.  Most DBAPIs have built in support for the datetime
module, with the noted exception of SQLite.  In the case of
SQLite, date and time types are stored as strings which are then
converted back to datetime objects when rows are returned.</p>
<dl class="method">
<dt id="sqlalchemy.types.DateTime.__init__">
<tt class="descname">__init__</tt><big>(</big><em>timezone=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.DateTime.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a new <a class="reference internal" href="#sqlalchemy.types.DateTime" title="sqlalchemy.types.DateTime"><tt class="xref py py-class docutils literal"><span class="pre">DateTime</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>timezone</strong> &#8211; boolean.  If True, and supported by the</td>
</tr>
</tbody>
</table>
<p>backend, will produce &#8216;TIMESTAMP WITH TIMEZONE&#8217;. For backends
that don&#8217;t support timezone aware timestamps, has no
effect.</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.Enum">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">Enum</tt><big>(</big><em>*enums</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.Enum" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.String" title="sqlalchemy.types.String"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.String</span></tt></a>, <a class="reference internal" href="#sqlalchemy.types.SchemaType" title="sqlalchemy.types.SchemaType"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.SchemaType</span></tt></a></p>
<p>Generic Enum Type.</p>
<p>The Enum type provides a set of possible string values which the
column is constrained towards.</p>
<p>By default, uses the backend&#8217;s native ENUM type if available,
else uses VARCHAR + a CHECK constraint.</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="../dialects/postgresql.html#sqlalchemy.dialects.postgresql.ENUM" title="sqlalchemy.dialects.postgresql.ENUM"><tt class="xref py py-class docutils literal"><span class="pre">ENUM</span></tt></a> - PostgreSQL-specific type,
which has additional functionality.</p>
</div>
<dl class="method">
<dt id="sqlalchemy.types.Enum.__init__">
<tt class="descname">__init__</tt><big>(</big><em>*enums</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.Enum.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct an enum.</p>
<p>Keyword arguments which don&#8217;t apply to a specific backend are ignored
by that backend.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>*enums</strong> &#8211; string or unicode enumeration labels. If unicode
labels are present, the <cite>convert_unicode</cite> flag is auto-enabled.</li>
<li><strong>convert_unicode</strong> &#8211; Enable unicode-aware bind parameter and
result-set processing for this Enum&#8217;s data. This is set
automatically based on the presence of unicode label strings.</li>
<li><strong>metadata</strong> &#8211; Associate this type directly with a <tt class="docutils literal"><span class="pre">MetaData</span></tt>
object. For types that exist on the target database as an
independent schema construct (Postgresql), this type will be
created and dropped within <tt class="docutils literal"><span class="pre">create_all()</span></tt> and <tt class="docutils literal"><span class="pre">drop_all()</span></tt>
operations. If the type is not associated with any <tt class="docutils literal"><span class="pre">MetaData</span></tt>
object, it will associate itself with each <tt class="docutils literal"><span class="pre">Table</span></tt> in which it is
used, and will be created when any of those individual tables are
created, after a check is performed for it&#8217;s existence. The type is
only dropped when <tt class="docutils literal"><span class="pre">drop_all()</span></tt> is called for that <tt class="docutils literal"><span class="pre">Table</span></tt>
object&#8217;s metadata, however.</li>
<li><strong>name</strong> &#8211; The name of this type. This is required for Postgresql
and any future supported database which requires an explicitly
named type, or an explicitly named constraint in order to generate
the type and/or a table that uses it.</li>
<li><strong>native_enum</strong> &#8211; Use the database&#8217;s native ENUM type when
available. Defaults to True. When False, uses VARCHAR + check
constraint for all backends.</li>
<li><strong>schema</strong> &#8211; <p>Schema name of this type. For types that exist on the
target database as an independent schema construct (Postgresql),
this parameter specifies the named schema in which the type is
present.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <tt class="docutils literal"><span class="pre">schema</span></tt> of the <a class="reference internal" href="#sqlalchemy.types.Enum" title="sqlalchemy.types.Enum"><tt class="xref py py-class docutils literal"><span class="pre">Enum</span></tt></a> type does not
by default make use of the <tt class="docutils literal"><span class="pre">schema</span></tt> established on the
owning <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>.  If this behavior is desired,
set the <tt class="docutils literal"><span class="pre">inherit_schema</span></tt> flag to <tt class="docutils literal"><span class="pre">True</span></tt>.</p>
</div>
</li>
<li><strong>quote</strong> &#8211; Force quoting to be on or off on the type&#8217;s name. If
left as the default of <cite>None</cite>, the usual schema-level &#8220;case
sensitive&#8221;/&#8221;reserved name&#8221; rules are used to determine if this
type&#8217;s name should be quoted.</li>
<li><strong>inherit_schema</strong> &#8211; <p>When <tt class="docutils literal"><span class="pre">True</span></tt>, the &#8220;schema&#8221; from the owning
<a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> will be copied to the &#8220;schema&#8221; attribute of this
<a class="reference internal" href="#sqlalchemy.types.Enum" title="sqlalchemy.types.Enum"><tt class="xref py py-class docutils literal"><span class="pre">Enum</span></tt></a>, replacing whatever value was passed for the
<tt class="docutils literal"><span class="pre">schema</span></tt> attribute.   This also takes effect when using the
<a class="reference internal" href="schema.html#sqlalchemy.schema.Table.tometadata" title="sqlalchemy.schema.Table.tometadata"><tt class="xref py py-meth docutils literal"><span class="pre">Table.tometadata()</span></tt></a> operation.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.8.</span></p>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.Enum.create">
<tt class="descname">create</tt><big>(</big><em>bind=None</em>, <em>checkfirst=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.Enum.create" title="Permalink to this definition">¶</a></dt>
<dd><p>Issue CREATE ddl for this type, if applicable.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.Enum.drop">
<tt class="descname">drop</tt><big>(</big><em>bind=None</em>, <em>checkfirst=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.Enum.drop" title="Permalink to this definition">¶</a></dt>
<dd><p>Issue DROP ddl for this type, if applicable.</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.Float">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">Float</tt><big>(</big><em>precision=None</em>, <em>asdecimal=False</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.Float" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.Numeric" title="sqlalchemy.types.Numeric"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.Numeric</span></tt></a></p>
<p>A type for <tt class="docutils literal"><span class="pre">float</span></tt> numbers.</p>
<p>Returns Python <tt class="docutils literal"><span class="pre">float</span></tt> objects by default, applying
conversion as needed.</p>
<dl class="method">
<dt id="sqlalchemy.types.Float.__init__">
<tt class="descname">__init__</tt><big>(</big><em>precision=None</em>, <em>asdecimal=False</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.Float.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a Float.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>precision</strong> &#8211; the numeric precision for use in DDL <tt class="docutils literal"><span class="pre">CREATE</span>
<span class="pre">TABLE</span></tt>.</li>
<li><strong>asdecimal</strong> &#8211; the same flag as that of <a class="reference internal" href="#sqlalchemy.types.Numeric" title="sqlalchemy.types.Numeric"><tt class="xref py py-class docutils literal"><span class="pre">Numeric</span></tt></a>, but
defaults to <tt class="docutils literal"><span class="pre">False</span></tt>.   Note that setting this flag to <tt class="docutils literal"><span class="pre">True</span></tt>
results in floating point conversion.</li>
<li><strong>**kwargs</strong> &#8211; deprecated.  Additional arguments here are ignored
by the default <a class="reference internal" href="#sqlalchemy.types.Float" title="sqlalchemy.types.Float"><tt class="xref py py-class docutils literal"><span class="pre">Float</span></tt></a> type.  For database specific
floats that support additional arguments, see that dialect&#8217;s
documentation for details, such as
<a class="reference internal" href="../dialects/mysql.html#sqlalchemy.dialects.mysql.FLOAT" title="sqlalchemy.dialects.mysql.FLOAT"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.dialects.mysql.FLOAT</span></tt></a>.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.Integer">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">Integer</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.Integer" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types._DateAffinity</span></tt>, <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.TypeEngine</span></tt></a></p>
<p>A type for <tt class="docutils literal"><span class="pre">int</span></tt> integers.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.Interval">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">Interval</tt><big>(</big><em>native=True</em>, <em>second_precision=None</em>, <em>day_precision=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.Interval" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types._DateAffinity</span></tt>, <a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.TypeDecorator</span></tt></a></p>
<p>A type for <tt class="docutils literal"><span class="pre">datetime.timedelta()</span></tt> objects.</p>
<p>The Interval type deals with <tt class="docutils literal"><span class="pre">datetime.timedelta</span></tt> objects.  In
PostgreSQL, the native <tt class="docutils literal"><span class="pre">INTERVAL</span></tt> type is used; for others, the
value is stored as a date which is relative to the &#8220;epoch&#8221;
(Jan. 1, 1970).</p>
<p>Note that the <tt class="docutils literal"><span class="pre">Interval</span></tt> type does not currently provide date arithmetic
operations on platforms which do not support interval types natively. Such
operations usually require transformation of both sides of the expression
(such as, conversion of both sides into integer epoch values first) which
currently is a manual procedure (such as via
<a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.func" title="sqlalchemy.sql.expression.func"><tt class="xref py py-attr docutils literal"><span class="pre">func</span></tt></a>).</p>
<dl class="method">
<dt id="sqlalchemy.types.Interval.__init__">
<tt class="descname">__init__</tt><big>(</big><em>native=True</em>, <em>second_precision=None</em>, <em>day_precision=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.Interval.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct an Interval object.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>native</strong> &#8211; when True, use the actual
INTERVAL type provided by the database, if
supported (currently Postgresql, Oracle).
Otherwise, represent the interval data as
an epoch value regardless.</li>
<li><strong>second_precision</strong> &#8211; For native interval types
which support a &#8220;fractional seconds precision&#8221; parameter,
i.e. Oracle and Postgresql</li>
<li><strong>day_precision</strong> &#8211; for native interval types which
support a &#8220;day precision&#8221; parameter, i.e. Oracle.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.Interval.coerce_compared_value">
<tt class="descname">coerce_compared_value</tt><big>(</big><em>op</em>, <em>value</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.Interval.coerce_compared_value" title="Permalink to this definition">¶</a></dt>
<dd><p>See <a class="reference internal" href="#sqlalchemy.types.TypeEngine.coerce_compared_value" title="sqlalchemy.types.TypeEngine.coerce_compared_value"><tt class="xref py py-meth docutils literal"><span class="pre">TypeEngine.coerce_compared_value()</span></tt></a> for a description.</p>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.types.Interval.impl">
<tt class="descname">impl</tt><a class="headerlink" href="#sqlalchemy.types.Interval.impl" title="Permalink to this definition">¶</a></dt>
<dd><p>alias of <a class="reference internal" href="#sqlalchemy.types.DateTime" title="sqlalchemy.types.DateTime"><tt class="xref py py-class docutils literal"><span class="pre">DateTime</span></tt></a></p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.LargeBinary">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">LargeBinary</tt><big>(</big><em>length=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.LargeBinary" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types._Binary</span></tt></p>
<p>A type for large binary byte data.</p>
<p>The Binary type generates BLOB or BYTEA when tables are created,
and also converts incoming values using the <tt class="docutils literal"><span class="pre">Binary</span></tt> callable
provided by each DB-API.</p>
<dl class="method">
<dt id="sqlalchemy.types.LargeBinary.__init__">
<tt class="descname">__init__</tt><big>(</big><em>length=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.LargeBinary.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a LargeBinary type.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>length</strong> &#8211; optional, a length for the column for use in
DDL statements, for those BLOB types that accept a length
(i.e. MySQL).  It does <em>not</em> produce a small BINARY/VARBINARY
type - use the BINARY/VARBINARY types specifically for those.
May be safely omitted if no <tt class="docutils literal"><span class="pre">CREATE</span>
<span class="pre">TABLE</span></tt> will be issued.  Certain databases may require a
<em>length</em> for use in DDL, and will raise an exception when
the <tt class="docutils literal"><span class="pre">CREATE</span> <span class="pre">TABLE</span></tt> DDL is issued.</td>
</tr>
</tbody>
</table>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.Numeric">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">Numeric</tt><big>(</big><em>precision=None</em>, <em>scale=None</em>, <em>asdecimal=True</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.Numeric" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types._DateAffinity</span></tt>, <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.TypeEngine</span></tt></a></p>
<p>A type for fixed precision numbers.</p>
<p>Typically generates DECIMAL or NUMERIC.  Returns
<tt class="docutils literal"><span class="pre">decimal.Decimal</span></tt> objects by default, applying
conversion as needed.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>The <a class="reference external" href="http://pypi.python.org/pypi/cdecimal/">cdecimal</a> library
is a high performing alternative to Python&#8217;s built-in
<tt class="docutils literal"><span class="pre">decimal.Decimal</span></tt> type, which performs very poorly in high volume
situations. SQLAlchemy 0.7 is tested against <tt class="docutils literal"><span class="pre">cdecimal</span></tt> and supports
it fully. The type is not necessarily supported by DBAPI
implementations however, most of which contain an import for plain
<tt class="docutils literal"><span class="pre">decimal</span></tt> in their source code, even though some such as psycopg2
provide hooks for alternate adapters. SQLAlchemy imports <tt class="docutils literal"><span class="pre">decimal</span></tt>
globally as well.  The most straightforward and
foolproof way to use &#8220;cdecimal&#8221; given current DBAPI and Python support
is to patch it directly into sys.modules before anything else is
imported:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">sys</span>
<span class="kn">import</span> <span class="nn">cdecimal</span>
<span class="n">sys</span><span class="o">.</span><span class="n">modules</span><span class="p">[</span><span class="s">&quot;decimal&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">cdecimal</span></pre></div>
</div>
<p>While the global patch is a little ugly, it&#8217;s particularly
important to use just one decimal library at a time since
Python Decimal and cdecimal Decimal objects
are not currently compatible <em>with each other</em>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">cdecimal</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">decimal</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">decimal</span><span class="o">.</span><span class="n">Decimal</span><span class="p">(</span><span class="s">&quot;10&quot;</span><span class="p">)</span> <span class="o">==</span> <span class="n">cdecimal</span><span class="o">.</span><span class="n">Decimal</span><span class="p">(</span><span class="s">&quot;10&quot;</span><span class="p">)</span>
<span class="go">False</span></pre></div>
</div>
<p class="last">SQLAlchemy will provide more natural support of
cdecimal if and when it becomes a standard part of Python
installations and is supported by all DBAPIs.</p>
</div>
<dl class="method">
<dt id="sqlalchemy.types.Numeric.__init__">
<tt class="descname">__init__</tt><big>(</big><em>precision=None</em>, <em>scale=None</em>, <em>asdecimal=True</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.Numeric.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a Numeric.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>precision</strong> &#8211; the numeric precision for use in DDL <tt class="docutils literal"><span class="pre">CREATE</span>
<span class="pre">TABLE</span></tt>.</li>
<li><strong>scale</strong> &#8211; the numeric scale for use in DDL <tt class="docutils literal"><span class="pre">CREATE</span> <span class="pre">TABLE</span></tt>.</li>
<li><strong>asdecimal</strong> &#8211; default True.  Return whether or not
values should be sent as Python Decimal objects, or
as floats.   Different DBAPIs send one or the other based on
datatypes - the Numeric type will ensure that return values
are one or the other across DBAPIs consistently.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>When using the <tt class="docutils literal"><span class="pre">Numeric</span></tt> type, care should be taken to ensure
that the asdecimal setting is apppropriate for the DBAPI in use -
when Numeric applies a conversion from Decimal-&gt;float or float-&gt;
Decimal, this conversion incurs an additional performance overhead
for all result columns received.</p>
<p>DBAPIs that return Decimal natively (e.g. psycopg2) will have
better accuracy and higher performance with a setting of <tt class="docutils literal"><span class="pre">True</span></tt>,
as the native translation to Decimal reduces the amount of floating-
point issues at play, and the Numeric type itself doesn&#8217;t need
to apply any further conversions.  However, another DBAPI which
returns floats natively <em>will</em> incur an additional conversion
overhead, and is still subject to floating point data loss - in
which case <tt class="docutils literal"><span class="pre">asdecimal=False</span></tt> will at least remove the extra
conversion overhead.</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.PickleType">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">PickleType</tt><big>(</big><em>protocol=2</em>, <em>pickler=None</em>, <em>comparator=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.PickleType" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.TypeDecorator</span></tt></a></p>
<p>Holds Python objects, which are serialized using pickle.</p>
<p>PickleType builds upon the Binary type to apply Python&#8217;s
<tt class="docutils literal"><span class="pre">pickle.dumps()</span></tt> to incoming objects, and <tt class="docutils literal"><span class="pre">pickle.loads()</span></tt> on
the way out, allowing any pickleable Python object to be stored as
a serialized binary field.</p>
<p>To allow ORM change events to propagate for elements associated
with <a class="reference internal" href="#sqlalchemy.types.PickleType" title="sqlalchemy.types.PickleType"><tt class="xref py py-class docutils literal"><span class="pre">PickleType</span></tt></a>, see <a class="reference internal" href="../orm/extensions/mutable.html"><em>Mutation Tracking</em></a>.</p>
<dl class="method">
<dt id="sqlalchemy.types.PickleType.__init__">
<tt class="descname">__init__</tt><big>(</big><em>protocol=2</em>, <em>pickler=None</em>, <em>comparator=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.PickleType.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a PickleType.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>protocol</strong> &#8211; defaults to <tt class="docutils literal"><span class="pre">pickle.HIGHEST_PROTOCOL</span></tt>.</li>
<li><strong>pickler</strong> &#8211; defaults to cPickle.pickle or pickle.pickle if
cPickle is not available.  May be any object with
pickle-compatible <tt class="docutils literal"><span class="pre">dumps`</span> <span class="pre">and</span> <span class="pre">``loads</span></tt> methods.</li>
<li><strong>comparator</strong> &#8211; a 2-arg callable predicate used
to compare values of this type.  If left as <tt class="docutils literal"><span class="pre">None</span></tt>,
the Python &#8220;equals&#8221; operator is used to compare values.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.types.PickleType.impl">
<tt class="descname">impl</tt><a class="headerlink" href="#sqlalchemy.types.PickleType.impl" title="Permalink to this definition">¶</a></dt>
<dd><p>alias of <a class="reference internal" href="#sqlalchemy.types.LargeBinary" title="sqlalchemy.types.LargeBinary"><tt class="xref py py-class docutils literal"><span class="pre">LargeBinary</span></tt></a></p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.SchemaType">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">SchemaType</tt><big>(</big><em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.SchemaType" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="events.html#sqlalchemy.events.SchemaEventTarget" title="sqlalchemy.events.SchemaEventTarget"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.events.SchemaEventTarget</span></tt></a></p>
<p>Mark a type as possibly requiring schema-level DDL for usage.</p>
<p>Supports types that must be explicitly created/dropped (i.e. PG ENUM type)
as well as types that are complimented by table or schema level
constraints, triggers, and other rules.</p>
<p><a class="reference internal" href="#sqlalchemy.types.SchemaType" title="sqlalchemy.types.SchemaType"><tt class="xref py py-class docutils literal"><span class="pre">SchemaType</span></tt></a> classes can also be targets for the
<a class="reference internal" href="events.html#sqlalchemy.events.DDLEvents.before_parent_attach" title="sqlalchemy.events.DDLEvents.before_parent_attach"><tt class="xref py py-meth docutils literal"><span class="pre">DDLEvents.before_parent_attach()</span></tt></a> and
<a class="reference internal" href="events.html#sqlalchemy.events.DDLEvents.after_parent_attach" title="sqlalchemy.events.DDLEvents.after_parent_attach"><tt class="xref py py-meth docutils literal"><span class="pre">DDLEvents.after_parent_attach()</span></tt></a> events, where the events fire off
surrounding the association of the type object with a parent
<a class="reference internal" href="schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a>.</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.types.Enum" title="sqlalchemy.types.Enum"><tt class="xref py py-class docutils literal"><span class="pre">Enum</span></tt></a></p>
<p class="last"><a class="reference internal" href="#sqlalchemy.types.Boolean" title="sqlalchemy.types.Boolean"><tt class="xref py py-class docutils literal"><span class="pre">Boolean</span></tt></a></p>
</div>
<dl class="method">
<dt id="sqlalchemy.types.SchemaType.adapt">
<tt class="descname">adapt</tt><big>(</big><em>impltype</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.SchemaType.adapt" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.types.SchemaType.bind">
<tt class="descname">bind</tt><a class="headerlink" href="#sqlalchemy.types.SchemaType.bind" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.SchemaType.copy">
<tt class="descname">copy</tt><big>(</big><em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.SchemaType.copy" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.SchemaType.create">
<tt class="descname">create</tt><big>(</big><em>bind=None</em>, <em>checkfirst=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.SchemaType.create" title="Permalink to this definition">¶</a></dt>
<dd><p>Issue CREATE ddl for this type, if applicable.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.SchemaType.drop">
<tt class="descname">drop</tt><big>(</big><em>bind=None</em>, <em>checkfirst=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.SchemaType.drop" title="Permalink to this definition">¶</a></dt>
<dd><p>Issue DROP ddl for this type, if applicable.</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.SmallInteger">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">SmallInteger</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.SmallInteger" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.Integer" title="sqlalchemy.types.Integer"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.Integer</span></tt></a></p>
<p>A type for smaller <tt class="docutils literal"><span class="pre">int</span></tt> integers.</p>
<p>Typically generates a <tt class="docutils literal"><span class="pre">SMALLINT</span></tt> in DDL, and otherwise acts like
a normal <a class="reference internal" href="#sqlalchemy.types.Integer" title="sqlalchemy.types.Integer"><tt class="xref py py-class docutils literal"><span class="pre">Integer</span></tt></a> on the Python side.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.String">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">String</tt><big>(</big><em>length=None</em>, <em>collation=None</em>, <em>convert_unicode=False</em>, <em>unicode_error=None</em>, <em>_warn_on_bytestring=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.String" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.Concatenable" title="sqlalchemy.types.Concatenable"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.Concatenable</span></tt></a>, <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.TypeEngine</span></tt></a></p>
<p>The base for all string and character types.</p>
<p>In SQL, corresponds to VARCHAR.  Can also take Python unicode objects
and encode to the database&#8217;s encoding in bind params (and the reverse for
result sets.)</p>
<p>The <cite>length</cite> field is usually required when the <cite>String</cite> type is
used within a CREATE TABLE statement, as VARCHAR requires a length
on most databases.</p>
<dl class="method">
<dt id="sqlalchemy.types.String.__init__">
<tt class="descname">__init__</tt><big>(</big><em>length=None</em>, <em>collation=None</em>, <em>convert_unicode=False</em>, <em>unicode_error=None</em>, <em>_warn_on_bytestring=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.String.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a string-holding type.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>length</strong> &#8211; optional, a length for the column for use in
DDL and CAST expressions.  May be safely omitted if no <tt class="docutils literal"><span class="pre">CREATE</span>
<span class="pre">TABLE</span></tt> will be issued.  Certain databases may require a
<tt class="docutils literal"><span class="pre">length</span></tt> for use in DDL, and will raise an exception when
the <tt class="docutils literal"><span class="pre">CREATE</span> <span class="pre">TABLE</span></tt> DDL is issued if a <tt class="docutils literal"><span class="pre">VARCHAR</span></tt>
with no length is included.  Whether the value is
interpreted as bytes or characters is database specific.</li>
<li><strong>collation</strong> &#8211; <p>Optional, a column-level collation for
use in DDL and CAST expressions.  Renders using the
COLLATE keyword supported by SQLite, MySQL, and Postgresql.
E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">cast</span><span class="p">,</span> <span class="n">select</span><span class="p">,</span> <span class="n">String</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">select</span><span class="p">([</span><span class="n">cast</span><span class="p">(</span><span class="s">&#39;some string&#39;</span><span class="p">,</span> <span class="n">String</span><span class="p">(</span><span class="n">collation</span><span class="o">=</span><span class="s">&#39;utf8&#39;</span><span class="p">))])</span>
<span class="go">SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1</span></pre></div>
</div>
<p class="versionadded">
<span class="versionmodified">New in version 0.8: </span>Added support for COLLATE to all
string types.</p>
</li>
<li><strong>convert_unicode</strong> &#8211; <p>When set to <tt class="docutils literal"><span class="pre">True</span></tt>, the
<a class="reference internal" href="#sqlalchemy.types.String" title="sqlalchemy.types.String"><tt class="xref py py-class docutils literal"><span class="pre">String</span></tt></a> type will assume that
input is to be passed as Python <tt class="docutils literal"><span class="pre">unicode</span></tt> objects,
and results returned as Python <tt class="docutils literal"><span class="pre">unicode</span></tt> objects.
If the DBAPI in use does not support Python unicode
(which is fewer and fewer these days), SQLAlchemy
will encode/decode the value, using the
value of the <tt class="docutils literal"><span class="pre">encoding</span></tt> parameter passed to
<a class="reference internal" href="engines.html#sqlalchemy.create_engine" title="sqlalchemy.create_engine"><tt class="xref py py-func docutils literal"><span class="pre">create_engine()</span></tt></a> as the encoding.</p>
<p>When using a DBAPI that natively supports Python
unicode objects, this flag generally does not
need to be set.  For columns that are explicitly
intended to store non-ASCII data, the <a class="reference internal" href="#sqlalchemy.types.Unicode" title="sqlalchemy.types.Unicode"><tt class="xref py py-class docutils literal"><span class="pre">Unicode</span></tt></a>
or <a class="reference internal" href="#sqlalchemy.types.UnicodeText" title="sqlalchemy.types.UnicodeText"><tt class="xref py py-class docutils literal"><span class="pre">UnicodeText</span></tt></a>
types should be used regardless, which feature
the same behavior of <tt class="docutils literal"><span class="pre">convert_unicode</span></tt> but
also indicate an underlying column type that
directly supports unicode, such as <tt class="docutils literal"><span class="pre">NVARCHAR</span></tt>.</p>
<p>For the extremely rare case that Python <tt class="docutils literal"><span class="pre">unicode</span></tt>
is to be encoded/decoded by SQLAlchemy on a backend
that does natively support Python <tt class="docutils literal"><span class="pre">unicode</span></tt>,
the value <tt class="docutils literal"><span class="pre">force</span></tt> can be passed here which will
cause SQLAlchemy&#8217;s encode/decode services to be
used unconditionally.</p>
</li>
<li><strong>unicode_error</strong> &#8211; Optional, a method to use to handle Unicode
conversion errors. Behaves like the <tt class="docutils literal"><span class="pre">errors</span></tt> keyword argument to
the standard library&#8217;s <tt class="docutils literal"><span class="pre">string.decode()</span></tt> functions.   This flag
requires that <tt class="docutils literal"><span class="pre">convert_unicode</span></tt> is set to <tt class="docutils literal"><span class="pre">force</span></tt> - otherwise,
SQLAlchemy is not guaranteed to handle the task of unicode
conversion.   Note that this flag adds significant performance
overhead to row-fetching operations for backends that already
return unicode objects natively (which most DBAPIs do).  This
flag should only be used as a last resort for reading
strings from a column with varied or corrupted encodings.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.Text">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">Text</tt><big>(</big><em>length=None</em>, <em>collation=None</em>, <em>convert_unicode=False</em>, <em>unicode_error=None</em>, <em>_warn_on_bytestring=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.Text" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.String" title="sqlalchemy.types.String"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.String</span></tt></a></p>
<p>A variably sized string type.</p>
<p>In SQL, usually corresponds to CLOB or TEXT. Can also take Python
unicode objects and encode to the database&#8217;s encoding in bind
params (and the reverse for result sets.)  In general, TEXT objects
do not have a length; while some databases will accept a length
argument here, it will be rejected by others.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.Time">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">Time</tt><big>(</big><em>timezone=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.Time" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types._DateAffinity</span></tt>, <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.TypeEngine</span></tt></a></p>
<p>A type for <tt class="docutils literal"><span class="pre">datetime.time()</span></tt> objects.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.Unicode">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">Unicode</tt><big>(</big><em>length=None</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.Unicode" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.String" title="sqlalchemy.types.String"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.String</span></tt></a></p>
<p>A variable length Unicode string type.</p>
<p>The <a class="reference internal" href="#sqlalchemy.types.Unicode" title="sqlalchemy.types.Unicode"><tt class="xref py py-class docutils literal"><span class="pre">Unicode</span></tt></a> type is a <a class="reference internal" href="#sqlalchemy.types.String" title="sqlalchemy.types.String"><tt class="xref py py-class docutils literal"><span class="pre">String</span></tt></a> subclass
that assumes input and output as Python <tt class="docutils literal"><span class="pre">unicode</span></tt> data,
and in that regard is equivalent to the usage of the
<tt class="docutils literal"><span class="pre">convert_unicode</span></tt> flag with the <a class="reference internal" href="#sqlalchemy.types.String" title="sqlalchemy.types.String"><tt class="xref py py-class docutils literal"><span class="pre">String</span></tt></a> type.
However, unlike plain <a class="reference internal" href="#sqlalchemy.types.String" title="sqlalchemy.types.String"><tt class="xref py py-class docutils literal"><span class="pre">String</span></tt></a>, it also implies an
underlying column type that is explicitly supporting of non-ASCII
data, such as <tt class="docutils literal"><span class="pre">NVARCHAR</span></tt> on Oracle and SQL Server.
This can impact the output of <tt class="docutils literal"><span class="pre">CREATE</span> <span class="pre">TABLE</span></tt> statements
and <tt class="docutils literal"><span class="pre">CAST</span></tt> functions at the dialect level, and can
also affect the handling of bound parameters in some
specific DBAPI scenarios.</p>
<p>The encoding used by the <a class="reference internal" href="#sqlalchemy.types.Unicode" title="sqlalchemy.types.Unicode"><tt class="xref py py-class docutils literal"><span class="pre">Unicode</span></tt></a> type is usually
determined by the DBAPI itself; most modern DBAPIs
feature support for Python <tt class="docutils literal"><span class="pre">unicode</span></tt> objects as bound
values and result set values, and the encoding should
be configured as detailed in the notes for the target
DBAPI in the <a class="reference internal" href="../dialects/index.html"><em>Dialects</em></a> section.</p>
<p>For those DBAPIs which do not support, or are not configured
to accommodate Python <tt class="docutils literal"><span class="pre">unicode</span></tt> objects
directly, SQLAlchemy does the encoding and decoding
outside of the DBAPI.   The encoding in this scenario
is determined by the <tt class="docutils literal"><span class="pre">encoding</span></tt> flag passed to
<a class="reference internal" href="engines.html#sqlalchemy.create_engine" title="sqlalchemy.create_engine"><tt class="xref py py-func docutils literal"><span class="pre">create_engine()</span></tt></a>.</p>
<p>When using the <a class="reference internal" href="#sqlalchemy.types.Unicode" title="sqlalchemy.types.Unicode"><tt class="xref py py-class docutils literal"><span class="pre">Unicode</span></tt></a> type, it is only appropriate
to pass Python <tt class="docutils literal"><span class="pre">unicode</span></tt> objects, and not plain <tt class="docutils literal"><span class="pre">str</span></tt>.
If a plain <tt class="docutils literal"><span class="pre">str</span></tt> is passed under Python 2, a warning
is emitted.  If you notice your application emitting these warnings but
you&#8217;re not sure of the source of them, the Python
<tt class="docutils literal"><span class="pre">warnings</span></tt> filter, documented at
<a class="reference external" href="http://docs.python.org/library/warnings.html">http://docs.python.org/library/warnings.html</a>,
can be used to turn these warnings into exceptions
which will illustrate a stack trace:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">warnings</span>
<span class="n">warnings</span><span class="o">.</span><span class="n">simplefilter</span><span class="p">(</span><span class="s">&#39;error&#39;</span><span class="p">)</span></pre></div>
</div>
<p>For an application that wishes to pass plain bytestrings
and Python <tt class="docutils literal"><span class="pre">unicode</span></tt> objects to the <tt class="docutils literal"><span class="pre">Unicode</span></tt> type
equally, the bytestrings must first be decoded into
unicode.  The recipe at <a class="reference internal" href="#coerce-to-unicode"><em>Coercing Encoded Strings to Unicode</em></a> illustrates
how this is done.</p>
<p>See also:</p>
<blockquote>
<div><a class="reference internal" href="#sqlalchemy.types.UnicodeText" title="sqlalchemy.types.UnicodeText"><tt class="xref py py-class docutils literal"><span class="pre">UnicodeText</span></tt></a> - unlengthed textual counterpart
to <a class="reference internal" href="#sqlalchemy.types.Unicode" title="sqlalchemy.types.Unicode"><tt class="xref py py-class docutils literal"><span class="pre">Unicode</span></tt></a>.</div></blockquote>
<dl class="method">
<dt id="sqlalchemy.types.Unicode.__init__">
<tt class="descname">__init__</tt><big>(</big><em>length=None</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.Unicode.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a <a class="reference internal" href="#sqlalchemy.types.Unicode" title="sqlalchemy.types.Unicode"><tt class="xref py py-class docutils literal"><span class="pre">Unicode</span></tt></a> object.</p>
<p>Parameters are the same as that of <a class="reference internal" href="#sqlalchemy.types.String" title="sqlalchemy.types.String"><tt class="xref py py-class docutils literal"><span class="pre">String</span></tt></a>,
with the exception that <tt class="docutils literal"><span class="pre">convert_unicode</span></tt>
defaults to <tt class="docutils literal"><span class="pre">True</span></tt>.</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.UnicodeText">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">UnicodeText</tt><big>(</big><em>length=None</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.UnicodeText" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.Text" title="sqlalchemy.types.Text"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.Text</span></tt></a></p>
<p>An unbounded-length Unicode string type.</p>
<p>See <a class="reference internal" href="#sqlalchemy.types.Unicode" title="sqlalchemy.types.Unicode"><tt class="xref py py-class docutils literal"><span class="pre">Unicode</span></tt></a> for details on the unicode
behavior of this object.</p>
<p>Like <a class="reference internal" href="#sqlalchemy.types.Unicode" title="sqlalchemy.types.Unicode"><tt class="xref py py-class docutils literal"><span class="pre">Unicode</span></tt></a>, usage the <a class="reference internal" href="#sqlalchemy.types.UnicodeText" title="sqlalchemy.types.UnicodeText"><tt class="xref py py-class docutils literal"><span class="pre">UnicodeText</span></tt></a> type implies a
unicode-capable type being used on the backend, such as
<tt class="docutils literal"><span class="pre">NCLOB</span></tt>, <tt class="docutils literal"><span class="pre">NTEXT</span></tt>.</p>
<dl class="method">
<dt id="sqlalchemy.types.UnicodeText.__init__">
<tt class="descname">__init__</tt><big>(</big><em>length=None</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.UnicodeText.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a Unicode-converting Text type.</p>
<p>Parameters are the same as that of <a class="reference internal" href="#sqlalchemy.types.Text" title="sqlalchemy.types.Text"><tt class="xref py py-class docutils literal"><span class="pre">Text</span></tt></a>,
with the exception that <tt class="docutils literal"><span class="pre">convert_unicode</span></tt>
defaults to <tt class="docutils literal"><span class="pre">True</span></tt>.</p>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="sql-standard-types">
<span id="types-sqlstandard"></span><h2>SQL Standard Types<a class="headerlink" href="#sql-standard-types" title="Permalink to this headline">¶</a></h2>
<p>The SQL standard types always create database column types of the same
name when <tt class="docutils literal"><span class="pre">CREATE</span> <span class="pre">TABLE</span></tt> is issued.  Some types may not be supported
on all databases.</p>
<dl class="class">
<dt id="sqlalchemy.types.BIGINT">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">BIGINT</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.BIGINT" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.BigInteger" title="sqlalchemy.types.BigInteger"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.BigInteger</span></tt></a></p>
<p>The SQL BIGINT type.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.BINARY">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">BINARY</tt><big>(</big><em>length=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.BINARY" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types._Binary</span></tt></p>
<p>The SQL BINARY type.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.BLOB">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">BLOB</tt><big>(</big><em>length=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.BLOB" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.LargeBinary" title="sqlalchemy.types.LargeBinary"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.LargeBinary</span></tt></a></p>
<p>The SQL BLOB type.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.BOOLEAN">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">BOOLEAN</tt><big>(</big><em>create_constraint=True</em>, <em>name=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.BOOLEAN" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.Boolean" title="sqlalchemy.types.Boolean"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.Boolean</span></tt></a></p>
<p>The SQL BOOLEAN type.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.CHAR">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">CHAR</tt><big>(</big><em>length=None</em>, <em>collation=None</em>, <em>convert_unicode=False</em>, <em>unicode_error=None</em>, <em>_warn_on_bytestring=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.CHAR" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.String" title="sqlalchemy.types.String"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.String</span></tt></a></p>
<p>The SQL CHAR type.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.CLOB">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">CLOB</tt><big>(</big><em>length=None</em>, <em>collation=None</em>, <em>convert_unicode=False</em>, <em>unicode_error=None</em>, <em>_warn_on_bytestring=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.CLOB" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.Text" title="sqlalchemy.types.Text"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.Text</span></tt></a></p>
<p>The CLOB type.</p>
<p>This type is found in Oracle and Informix.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.DATE">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">DATE</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.DATE" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.Date" title="sqlalchemy.types.Date"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.Date</span></tt></a></p>
<p>The SQL DATE type.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.DATETIME">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">DATETIME</tt><big>(</big><em>timezone=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.DATETIME" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.DateTime" title="sqlalchemy.types.DateTime"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.DateTime</span></tt></a></p>
<p>The SQL DATETIME type.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.DECIMAL">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">DECIMAL</tt><big>(</big><em>precision=None</em>, <em>scale=None</em>, <em>asdecimal=True</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.DECIMAL" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.Numeric" title="sqlalchemy.types.Numeric"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.Numeric</span></tt></a></p>
<p>The SQL DECIMAL type.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.FLOAT">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">FLOAT</tt><big>(</big><em>precision=None</em>, <em>asdecimal=False</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.FLOAT" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.Float" title="sqlalchemy.types.Float"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.Float</span></tt></a></p>
<p>The SQL FLOAT type.</p>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.types.INT">
<tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">INT</tt><a class="headerlink" href="#sqlalchemy.types.INT" title="Permalink to this definition">¶</a></dt>
<dd><p>alias of <a class="reference internal" href="#sqlalchemy.types.INTEGER" title="sqlalchemy.types.INTEGER"><tt class="xref py py-class docutils literal"><span class="pre">INTEGER</span></tt></a></p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.INTEGER">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">INTEGER</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.INTEGER" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.Integer" title="sqlalchemy.types.Integer"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.Integer</span></tt></a></p>
<p>The SQL INT or INTEGER type.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.NCHAR">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">NCHAR</tt><big>(</big><em>length=None</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.NCHAR" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.Unicode" title="sqlalchemy.types.Unicode"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.Unicode</span></tt></a></p>
<p>The SQL NCHAR type.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.NVARCHAR">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">NVARCHAR</tt><big>(</big><em>length=None</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.NVARCHAR" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.Unicode" title="sqlalchemy.types.Unicode"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.Unicode</span></tt></a></p>
<p>The SQL NVARCHAR type.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.NUMERIC">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">NUMERIC</tt><big>(</big><em>precision=None</em>, <em>scale=None</em>, <em>asdecimal=True</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.NUMERIC" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.Numeric" title="sqlalchemy.types.Numeric"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.Numeric</span></tt></a></p>
<p>The SQL NUMERIC type.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.REAL">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">REAL</tt><big>(</big><em>precision=None</em>, <em>asdecimal=False</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.REAL" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.Float" title="sqlalchemy.types.Float"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.Float</span></tt></a></p>
<p>The SQL REAL type.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.SMALLINT">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">SMALLINT</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.SMALLINT" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.SmallInteger" title="sqlalchemy.types.SmallInteger"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.SmallInteger</span></tt></a></p>
<p>The SQL SMALLINT type.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.TEXT">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">TEXT</tt><big>(</big><em>length=None</em>, <em>collation=None</em>, <em>convert_unicode=False</em>, <em>unicode_error=None</em>, <em>_warn_on_bytestring=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TEXT" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.Text" title="sqlalchemy.types.Text"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.Text</span></tt></a></p>
<p>The SQL TEXT type.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.TIME">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">TIME</tt><big>(</big><em>timezone=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TIME" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.Time" title="sqlalchemy.types.Time"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.Time</span></tt></a></p>
<p>The SQL TIME type.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.TIMESTAMP">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">TIMESTAMP</tt><big>(</big><em>timezone=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TIMESTAMP" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.DateTime" title="sqlalchemy.types.DateTime"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.DateTime</span></tt></a></p>
<p>The SQL TIMESTAMP type.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.VARBINARY">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">VARBINARY</tt><big>(</big><em>length=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.VARBINARY" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types._Binary</span></tt></p>
<p>The SQL VARBINARY type.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.VARCHAR">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">VARCHAR</tt><big>(</big><em>length=None</em>, <em>collation=None</em>, <em>convert_unicode=False</em>, <em>unicode_error=None</em>, <em>_warn_on_bytestring=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.VARCHAR" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.String" title="sqlalchemy.types.String"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.String</span></tt></a></p>
<p>The SQL VARCHAR type.</p>
</dd></dl>

</div>
<div class="section" id="vendor-specific-types">
<span id="types-vendor"></span><h2>Vendor-Specific Types<a class="headerlink" href="#vendor-specific-types" title="Permalink to this headline">¶</a></h2>
<p>Database-specific types are also available for import from each
database&#8217;s dialect module. See the <em class="xref std std-ref">sqlalchemy.dialects_toplevel</em>
reference for the database you&#8217;re interested in.</p>
<p>For example, MySQL has a <tt class="docutils literal"><span class="pre">BIGINT</span></tt> type and PostgreSQL has an
<tt class="docutils literal"><span class="pre">INET</span></tt> type.  To use these, import them from the module explicitly:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.dialects</span> <span class="kn">import</span> <span class="n">mysql</span>

<span class="n">table</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s">&#39;foo&#39;</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span>
    <span class="n">Column</span><span class="p">(</span><span class="s">&#39;id&#39;</span><span class="p">,</span> <span class="n">mysql</span><span class="o">.</span><span class="n">BIGINT</span><span class="p">),</span>
    <span class="n">Column</span><span class="p">(</span><span class="s">&#39;enumerates&#39;</span><span class="p">,</span> <span class="n">mysql</span><span class="o">.</span><span class="n">ENUM</span><span class="p">(</span><span class="s">&#39;a&#39;</span><span class="p">,</span> <span class="s">&#39;b&#39;</span><span class="p">,</span> <span class="s">&#39;c&#39;</span><span class="p">))</span>
<span class="p">)</span></pre></div>
</div>
<p>Or some PostgreSQL types:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.dialects</span> <span class="kn">import</span> <span class="n">postgresql</span>

<span class="n">table</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s">&#39;foo&#39;</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span>
    <span class="n">Column</span><span class="p">(</span><span class="s">&#39;ipaddress&#39;</span><span class="p">,</span> <span class="n">postgresql</span><span class="o">.</span><span class="n">INET</span><span class="p">),</span>
    <span class="n">Column</span><span class="p">(</span><span class="s">&#39;elements&#39;</span><span class="p">,</span> <span class="n">postgresql</span><span class="o">.</span><span class="n">ARRAY</span><span class="p">(</span><span class="n">String</span><span class="p">))</span>
<span class="p">)</span></pre></div>
</div>
<p>Each dialect provides the full set of typenames supported by
that backend within its <cite>__all__</cite> collection, so that a simple
<cite>import *</cite> or similar will import all supported types as
implemented for that backend:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.dialects.postgresql</span> <span class="kn">import</span> <span class="o">*</span>

<span class="n">t</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s">&#39;mytable&#39;</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span>
           <span class="n">Column</span><span class="p">(</span><span class="s">&#39;id&#39;</span><span class="p">,</span> <span class="n">INTEGER</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">),</span>
           <span class="n">Column</span><span class="p">(</span><span class="s">&#39;name&#39;</span><span class="p">,</span> <span class="n">VARCHAR</span><span class="p">(</span><span class="mi">300</span><span class="p">)),</span>
           <span class="n">Column</span><span class="p">(</span><span class="s">&#39;inetaddr&#39;</span><span class="p">,</span> <span class="n">INET</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>Where above, the INTEGER and VARCHAR types are ultimately from
sqlalchemy.types, and INET is specific to the Postgresql dialect.</p>
<p>Some dialect level types have the same name as the SQL standard type,
but also provide additional arguments.  For example, MySQL implements
the full range of character and string types including additional arguments
such as <cite>collation</cite> and <cite>charset</cite>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.dialects.mysql</span> <span class="kn">import</span> <span class="n">VARCHAR</span><span class="p">,</span> <span class="n">TEXT</span>

<span class="n">table</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s">&#39;foo&#39;</span><span class="p">,</span> <span class="n">meta</span><span class="p">,</span>
    <span class="n">Column</span><span class="p">(</span><span class="s">&#39;col1&#39;</span><span class="p">,</span> <span class="n">VARCHAR</span><span class="p">(</span><span class="mi">200</span><span class="p">,</span> <span class="n">collation</span><span class="o">=</span><span class="s">&#39;binary&#39;</span><span class="p">)),</span>
    <span class="n">Column</span><span class="p">(</span><span class="s">&#39;col2&#39;</span><span class="p">,</span> <span class="n">TEXT</span><span class="p">(</span><span class="n">charset</span><span class="o">=</span><span class="s">&#39;latin1&#39;</span><span class="p">))</span>
<span class="p">)</span></pre></div>
</div>
</div>
<div class="section" id="custom-types">
<span id="types-custom"></span><h2>Custom Types<a class="headerlink" href="#custom-types" title="Permalink to this headline">¶</a></h2>
<p>A variety of methods exist to redefine the behavior of existing types
as well as to provide new ones.</p>
<div class="section" id="overriding-type-compilation">
<h3>Overriding Type Compilation<a class="headerlink" href="#overriding-type-compilation" title="Permalink to this headline">¶</a></h3>
<p>A frequent need is to force the &#8220;string&#8221; version of a type, that is
the one rendered in a CREATE TABLE statement or other SQL function
like CAST, to be changed.   For example, an application may want
to force the rendering of <tt class="docutils literal"><span class="pre">BINARY</span></tt> for all platforms
except for one, in which is wants <tt class="docutils literal"><span class="pre">BLOB</span></tt> to be rendered.  Usage
of an existing generic type, in this case <a class="reference internal" href="#sqlalchemy.types.LargeBinary" title="sqlalchemy.types.LargeBinary"><tt class="xref py py-class docutils literal"><span class="pre">LargeBinary</span></tt></a>, is
preferred for most use cases.  But to control
types more accurately, a compilation directive that is per-dialect
can be associated with any type:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.ext.compiler</span> <span class="kn">import</span> <span class="n">compiles</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.types</span> <span class="kn">import</span> <span class="n">BINARY</span>

<span class="nd">@compiles</span><span class="p">(</span><span class="n">BINARY</span><span class="p">,</span> <span class="s">&quot;sqlite&quot;</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">compile_binary_sqlite</span><span class="p">(</span><span class="n">type_</span><span class="p">,</span> <span class="n">compiler</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">):</span>
    <span class="k">return</span> <span class="s">&quot;BLOB&quot;</span></pre></div>
</div>
<p>The above code allows the usage of <a class="reference internal" href="#sqlalchemy.types.BINARY" title="sqlalchemy.types.BINARY"><tt class="xref py py-class docutils literal"><span class="pre">types.BINARY</span></tt></a>, which
will produce the string <tt class="docutils literal"><span class="pre">BINARY</span></tt> against all backends except SQLite,
in which case it will produce <tt class="docutils literal"><span class="pre">BLOB</span></tt>.</p>
<p>See the section <a class="reference internal" href="compiler.html#type-compilation-extension"><em>Changing Compilation of Types</em></a>, a subsection of
<a class="reference internal" href="compiler.html"><em>Custom SQL Constructs and Compilation Extension</em></a>, for additional examples.</p>
</div>
<div class="section" id="augmenting-existing-types">
<span id="types-typedecorator"></span><h3>Augmenting Existing Types<a class="headerlink" href="#augmenting-existing-types" title="Permalink to this headline">¶</a></h3>
<p>The <a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">TypeDecorator</span></tt></a> allows the creation of custom types which
add bind-parameter and result-processing behavior to an existing
type object.  It is used when additional in-Python marshaling of data
to and from the database is required.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The bind- and result-processing of <a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">TypeDecorator</span></tt></a>
is <em>in addition</em> to the processing already performed by the hosted
type, which is customized by SQLAlchemy on a per-DBAPI basis to perform
processing specific to that DBAPI.  To change the DBAPI-level processing
for an existing type, see the section <a class="reference internal" href="#replacing-processors"><em>Replacing the Bind/Result Processing of Existing Types</em></a>.</p>
</div>
<dl class="class">
<dt id="sqlalchemy.types.TypeDecorator">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">TypeDecorator</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeDecorator" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.TypeEngine</span></tt></a></p>
<p>Allows the creation of types which add additional functionality
to an existing type.</p>
<p>This method is preferred to direct subclassing of SQLAlchemy&#8217;s
built-in types as it ensures that all required functionality of
the underlying type is kept in place.</p>
<p>Typical usage:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">sqlalchemy.types</span> <span class="kn">as</span> <span class="nn">types</span>

<span class="k">class</span> <span class="nc">MyType</span><span class="p">(</span><span class="n">types</span><span class="o">.</span><span class="n">TypeDecorator</span><span class="p">):</span>
    <span class="sd">&#39;&#39;&#39;Prefixes Unicode values with &quot;PREFIX:&quot; on the way in and</span>
<span class="sd">    strips it off on the way out.</span>
<span class="sd">    &#39;&#39;&#39;</span>

    <span class="n">impl</span> <span class="o">=</span> <span class="n">types</span><span class="o">.</span><span class="n">Unicode</span>

    <span class="k">def</span> <span class="nf">process_bind_param</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">dialect</span><span class="p">):</span>
        <span class="k">return</span> <span class="s">&quot;PREFIX:&quot;</span> <span class="o">+</span> <span class="n">value</span>

    <span class="k">def</span> <span class="nf">process_result_value</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">dialect</span><span class="p">):</span>
        <span class="k">return</span> <span class="n">value</span><span class="p">[</span><span class="mi">7</span><span class="p">:]</span>

    <span class="k">def</span> <span class="nf">copy</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="n">MyType</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">impl</span><span class="o">.</span><span class="n">length</span><span class="p">)</span></pre></div>
</div>
<p>The class-level &#8220;impl&#8221; attribute is required, and can reference any
TypeEngine class.  Alternatively, the load_dialect_impl() method
can be used to provide different type classes based on the dialect
given; in this case, the &#8220;impl&#8221; variable can reference
<tt class="docutils literal"><span class="pre">TypeEngine</span></tt> as a placeholder.</p>
<p>Types that receive a Python type that isn&#8217;t similar to the ultimate type
used may want to define the <a class="reference internal" href="#sqlalchemy.types.TypeDecorator.coerce_compared_value" title="sqlalchemy.types.TypeDecorator.coerce_compared_value"><tt class="xref py py-meth docutils literal"><span class="pre">TypeDecorator.coerce_compared_value()</span></tt></a>
method. This is used to give the expression system a hint when coercing
Python objects into bind parameters within expressions. Consider this
expression:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">mytable</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">somecol</span> <span class="o">+</span> <span class="n">datetime</span><span class="o">.</span><span class="n">date</span><span class="p">(</span><span class="mi">2009</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">15</span><span class="p">)</span></pre></div>
</div>
<p>Above, if &#8220;somecol&#8221; is an <tt class="docutils literal"><span class="pre">Integer</span></tt> variant, it makes sense that
we&#8217;re doing date arithmetic, where above is usually interpreted
by databases as adding a number of days to the given date.
The expression system does the right thing by not attempting to
coerce the &#8220;date()&#8221; value into an integer-oriented bind parameter.</p>
<p>However, in the case of <tt class="docutils literal"><span class="pre">TypeDecorator</span></tt>, we are usually changing an
incoming Python type to something new - <tt class="docutils literal"><span class="pre">TypeDecorator</span></tt> by default will
&#8220;coerce&#8221; the non-typed side to be the same type as itself. Such as below,
we define an &#8220;epoch&#8221; type that stores a date value as an integer:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyEpochType</span><span class="p">(</span><span class="n">types</span><span class="o">.</span><span class="n">TypeDecorator</span><span class="p">):</span>
    <span class="n">impl</span> <span class="o">=</span> <span class="n">types</span><span class="o">.</span><span class="n">Integer</span>

    <span class="n">epoch</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">date</span><span class="p">(</span><span class="mi">1970</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">process_bind_param</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">dialect</span><span class="p">):</span>
        <span class="k">return</span> <span class="p">(</span><span class="n">value</span> <span class="o">-</span> <span class="bp">self</span><span class="o">.</span><span class="n">epoch</span><span class="p">)</span><span class="o">.</span><span class="n">days</span>

    <span class="k">def</span> <span class="nf">process_result_value</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">dialect</span><span class="p">):</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">epoch</span> <span class="o">+</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">days</span><span class="o">=</span><span class="n">value</span><span class="p">)</span></pre></div>
</div>
<p>Our expression of <tt class="docutils literal"><span class="pre">somecol</span> <span class="pre">+</span> <span class="pre">date</span></tt> with the above type will coerce the
&#8220;date&#8221; on the right side to also be treated as <tt class="docutils literal"><span class="pre">MyEpochType</span></tt>.</p>
<p>This behavior can be overridden via the
<a class="reference internal" href="#sqlalchemy.types.TypeDecorator.coerce_compared_value" title="sqlalchemy.types.TypeDecorator.coerce_compared_value"><tt class="xref py py-meth docutils literal"><span class="pre">coerce_compared_value()</span></tt></a> method, which returns a type
that should be used for the value of the expression. Below we set it such
that an integer value will be treated as an <tt class="docutils literal"><span class="pre">Integer</span></tt>, and any other
value is assumed to be a date and will be treated as a <tt class="docutils literal"><span class="pre">MyEpochType</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">coerce_compared_value</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">op</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>
    <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="nb">int</span><span class="p">):</span>
        <span class="k">return</span> <span class="n">Integer</span><span class="p">()</span>
    <span class="k">else</span><span class="p">:</span>
        <span class="k">return</span> <span class="bp">self</span></pre></div>
</div>
<dl class="method">
<dt id="sqlalchemy.types.TypeDecorator.__init__">
<tt class="descname">__init__</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeDecorator.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a <a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">TypeDecorator</span></tt></a>.</p>
<p>Arguments sent here are passed to the constructor
of the class assigned to the <tt class="docutils literal"><span class="pre">impl</span></tt> class level attribute,
assuming the <tt class="docutils literal"><span class="pre">impl</span></tt> is a callable, and the resulting
object is assigned to the <tt class="docutils literal"><span class="pre">self.impl</span></tt> instance attribute
(thus overriding the class attribute of the same name).</p>
<p>If the class level <tt class="docutils literal"><span class="pre">impl</span></tt> is not a callable (the unusual case),
it will be assigned to the same instance attribute &#8216;as-is&#8217;,
ignoring those arguments passed to the constructor.</p>
<p>Subclasses can override this to customize the generation
of <tt class="docutils literal"><span class="pre">self.impl</span></tt> entirely.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeDecorator.adapt">
<tt class="descname">adapt</tt><big>(</big><em>cls</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeDecorator.adapt" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.types.TypeEngine.adapt" title="sqlalchemy.types.TypeEngine.adapt"><tt class="xref py py-meth docutils literal"><span class="pre">adapt()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a></div>
<p>Produce an &#8220;adapted&#8221; form of this type, given an &#8220;impl&#8221; class
to work with.</p>
<p>This method is used internally to associate generic
types with &#8220;implementation&#8221; types that are specific to a particular
dialect.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeDecorator.bind_expression">
<tt class="descname">bind_expression</tt><big>(</big><em>bindvalue</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeDecorator.bind_expression" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.types.TypeEngine.bind_expression" title="sqlalchemy.types.TypeEngine.bind_expression"><tt class="xref py py-meth docutils literal"><span class="pre">bind_expression()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a></div>
<p>&#8220;Given a bind value (i.e. a <a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.BindParameter" title="sqlalchemy.sql.expression.BindParameter"><tt class="xref py py-class docutils literal"><span class="pre">BindParameter</span></tt></a> instance),
return a SQL expression in its place.</p>
<p>This is typically a SQL function that wraps the existing bound
parameter within the statement.  It is used for special data types
that require literals being wrapped in some special database function
in order to coerce an application-level value into a database-specific
format.  It is the SQL analogue of the
<a class="reference internal" href="#sqlalchemy.types.TypeEngine.bind_processor" title="sqlalchemy.types.TypeEngine.bind_processor"><tt class="xref py py-meth docutils literal"><span class="pre">TypeEngine.bind_processor()</span></tt></a> method.</p>
<p>The method is evaluated at statement compile time, as opposed
to statement construction time.</p>
<p>Note that this method, when implemented, should always return
the exact same structure, without any conditional logic, as it
may be used in an executemany() call against an arbitrary number
of bound parameter sets.</p>
<p>See also:</p>
<p><a class="reference internal" href="#types-sql-value-processing"><em>Applying SQL-level Bind/Result Processing</em></a></p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeDecorator.bind_processor">
<tt class="descname">bind_processor</tt><big>(</big><em>dialect</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeDecorator.bind_processor" title="Permalink to this definition">¶</a></dt>
<dd><p>Provide a bound value processing function for the
given <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Dialect" title="sqlalchemy.engine.interfaces.Dialect"><tt class="xref py py-class docutils literal"><span class="pre">Dialect</span></tt></a>.</p>
<p>This is the method that fulfills the <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a>
contract for bound value conversion.   <a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">TypeDecorator</span></tt></a>
will wrap a user-defined implementation of
<a class="reference internal" href="#sqlalchemy.types.TypeDecorator.process_bind_param" title="sqlalchemy.types.TypeDecorator.process_bind_param"><tt class="xref py py-meth docutils literal"><span class="pre">process_bind_param()</span></tt></a> here.</p>
<p>User-defined code can override this method directly,
though its likely best to use <a class="reference internal" href="#sqlalchemy.types.TypeDecorator.process_bind_param" title="sqlalchemy.types.TypeDecorator.process_bind_param"><tt class="xref py py-meth docutils literal"><span class="pre">process_bind_param()</span></tt></a> so that
the processing provided by <tt class="docutils literal"><span class="pre">self.impl</span></tt> is maintained.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>dialect</strong> &#8211; Dialect instance in use.</td>
</tr>
</tbody>
</table>
<p>This method is the reverse counterpart to the
<a class="reference internal" href="#sqlalchemy.types.TypeDecorator.result_processor" title="sqlalchemy.types.TypeDecorator.result_processor"><tt class="xref py py-meth docutils literal"><span class="pre">result_processor()</span></tt></a> method of this class.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeDecorator.coerce_compared_value">
<tt class="descname">coerce_compared_value</tt><big>(</big><em>op</em>, <em>value</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeDecorator.coerce_compared_value" title="Permalink to this definition">¶</a></dt>
<dd><p>Suggest a type for a &#8216;coerced&#8217; Python value in an expression.</p>
<p>By default, returns self.   This method is called by
the expression system when an object using this type is
on the left or right side of an expression against a plain Python
object which does not yet have a SQLAlchemy type assigned:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">expr</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">somecolumn</span> <span class="o">+</span> <span class="mi">35</span></pre></div>
</div>
<p>Where above, if <tt class="docutils literal"><span class="pre">somecolumn</span></tt> uses this type, this method will
be called with the value <tt class="docutils literal"><span class="pre">operator.add</span></tt>
and <tt class="docutils literal"><span class="pre">35</span></tt>.  The return value is whatever SQLAlchemy type should
be used for <tt class="docutils literal"><span class="pre">35</span></tt> for this particular operation.</p>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.types.TypeDecorator.coerce_to_is_types">
<tt class="descname">coerce_to_is_types</tt><em class="property"> = (&lt;type 'NoneType'&gt;,)</em><a class="headerlink" href="#sqlalchemy.types.TypeDecorator.coerce_to_is_types" title="Permalink to this definition">¶</a></dt>
<dd><p>Specify those Python types which should be coerced at the expression
level to &#8220;IS &lt;constant&gt;&#8221; when compared using <tt class="docutils literal"><span class="pre">==</span></tt> (and same for</p>
<blockquote>
<div><tt class="docutils literal"><span class="pre">IS</span> <span class="pre">NOT</span></tt> in conjunction with <tt class="docutils literal"><span class="pre">!=</span></tt>.</div></blockquote>
<p>For most SQLAlchemy types, this includes <tt class="docutils literal"><span class="pre">NoneType</span></tt>, as well as <tt class="docutils literal"><span class="pre">bool</span></tt>.</p>
<p><a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">TypeDecorator</span></tt></a> modifies this list to only include <tt class="docutils literal"><span class="pre">NoneType</span></tt>,
as typedecorator implementations that deal with boolean types are common.</p>
<p>Custom <a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">TypeDecorator</span></tt></a> classes can override this attribute to
return an empty tuple, in which case no values will be coerced to
constants.</p>
<dl class="docutils">
<dt>..versionadded:: 0.8.2</dt>
<dd>Added <a class="reference internal" href="#sqlalchemy.types.TypeDecorator.coerce_to_is_types" title="sqlalchemy.types.TypeDecorator.coerce_to_is_types"><tt class="xref py py-attr docutils literal"><span class="pre">TypeDecorator.coerce_to_is_types</span></tt></a> to allow for easier
control of <tt class="docutils literal"><span class="pre">__eq__()</span></tt> <tt class="docutils literal"><span class="pre">__ne__()</span></tt> operations.</dd>
</dl>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeDecorator.column_expression">
<tt class="descname">column_expression</tt><big>(</big><em>colexpr</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeDecorator.column_expression" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.types.TypeEngine.column_expression" title="sqlalchemy.types.TypeEngine.column_expression"><tt class="xref py py-meth docutils literal"><span class="pre">column_expression()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a></div>
<p>Given a SELECT column expression, return a wrapping SQL expression.</p>
<p>This is typically a SQL function that wraps a column expression
as rendered in the columns clause of a SELECT statement.
It is used for special data types that require
columns to be wrapped in some special database function in order
to coerce the value before being sent back to the application.
It is the SQL analogue of the <a class="reference internal" href="#sqlalchemy.types.TypeEngine.result_processor" title="sqlalchemy.types.TypeEngine.result_processor"><tt class="xref py py-meth docutils literal"><span class="pre">TypeEngine.result_processor()</span></tt></a>
method.</p>
<p>The method is evaluated at statement compile time, as opposed
to statement construction time.</p>
<p>See also:</p>
<p><a class="reference internal" href="#types-sql-value-processing"><em>Applying SQL-level Bind/Result Processing</em></a></p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeDecorator.compare_values">
<tt class="descname">compare_values</tt><big>(</big><em>x</em>, <em>y</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeDecorator.compare_values" title="Permalink to this definition">¶</a></dt>
<dd><p>Given two values, compare them for equality.</p>
<p>By default this calls upon <a class="reference internal" href="#sqlalchemy.types.TypeEngine.compare_values" title="sqlalchemy.types.TypeEngine.compare_values"><tt class="xref py py-meth docutils literal"><span class="pre">TypeEngine.compare_values()</span></tt></a>
of the underlying &#8220;impl&#8221;, which in turn usually
uses the Python equals operator <tt class="docutils literal"><span class="pre">==</span></tt>.</p>
<p>This function is used by the ORM to compare
an original-loaded value with an intercepted
&#8220;changed&#8221; value, to determine if a net change
has occurred.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeDecorator.compile">
<tt class="descname">compile</tt><big>(</big><em>dialect=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeDecorator.compile" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.types.TypeEngine.compile" title="sqlalchemy.types.TypeEngine.compile"><tt class="xref py py-meth docutils literal"><span class="pre">compile()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a></div>
<p>Produce a string-compiled form of this <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a>.</p>
<p>When called with no arguments, uses a &#8220;default&#8221; dialect
to produce a string result.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>dialect</strong> &#8211; a <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Dialect" title="sqlalchemy.engine.interfaces.Dialect"><tt class="xref py py-class docutils literal"><span class="pre">Dialect</span></tt></a> instance.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeDecorator.copy">
<tt class="descname">copy</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeDecorator.copy" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a copy of this <a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">TypeDecorator</span></tt></a> instance.</p>
<p>This is a shallow copy and is provided to fulfill part of
the <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a> contract.  It usually does not
need to be overridden unless the user-defined <a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">TypeDecorator</span></tt></a>
has local state that should be deep-copied.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeDecorator.dialect_impl">
<tt class="descname">dialect_impl</tt><big>(</big><em>dialect</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeDecorator.dialect_impl" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.types.TypeEngine.dialect_impl" title="sqlalchemy.types.TypeEngine.dialect_impl"><tt class="xref py py-meth docutils literal"><span class="pre">dialect_impl()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a></div>
<p>Return a dialect-specific implementation for this
<a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a>.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeDecorator.get_dbapi_type">
<tt class="descname">get_dbapi_type</tt><big>(</big><em>dbapi</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeDecorator.get_dbapi_type" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the DBAPI type object represented by this
<a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">TypeDecorator</span></tt></a>.</p>
<p>By default this calls upon <a class="reference internal" href="#sqlalchemy.types.TypeEngine.get_dbapi_type" title="sqlalchemy.types.TypeEngine.get_dbapi_type"><tt class="xref py py-meth docutils literal"><span class="pre">TypeEngine.get_dbapi_type()</span></tt></a> of the
underlying &#8220;impl&#8221;.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeDecorator.load_dialect_impl">
<tt class="descname">load_dialect_impl</tt><big>(</big><em>dialect</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeDecorator.load_dialect_impl" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a> object corresponding to a dialect.</p>
<p>This is an end-user override hook that can be used to provide
differing types depending on the given dialect.  It is used
by the <a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">TypeDecorator</span></tt></a> implementation of <a class="reference internal" href="#sqlalchemy.types.TypeDecorator.type_engine" title="sqlalchemy.types.TypeDecorator.type_engine"><tt class="xref py py-meth docutils literal"><span class="pre">type_engine()</span></tt></a>
to help determine what type should ultimately be returned
for a given <a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">TypeDecorator</span></tt></a>.</p>
<p>By default returns <tt class="docutils literal"><span class="pre">self.impl</span></tt>.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeDecorator.process_bind_param">
<tt class="descname">process_bind_param</tt><big>(</big><em>value</em>, <em>dialect</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeDecorator.process_bind_param" title="Permalink to this definition">¶</a></dt>
<dd><p>Receive a bound parameter value to be converted.</p>
<p>Subclasses override this method to return the
value that should be passed along to the underlying
<a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a> object, and from there to the
DBAPI <tt class="docutils literal"><span class="pre">execute()</span></tt> method.</p>
<p>The operation could be anything desired to perform custom
behavior, such as transforming or serializing data.
This could also be used as a hook for validating logic.</p>
<p>This operation should be designed with the reverse operation
in mind, which would be the process_result_value method of
this class.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>value</strong> &#8211; Data to operate upon, of any type expected by
this method in the subclass.  Can be <tt class="docutils literal"><span class="pre">None</span></tt>.</li>
<li><strong>dialect</strong> &#8211; the <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Dialect" title="sqlalchemy.engine.interfaces.Dialect"><tt class="xref py py-class docutils literal"><span class="pre">Dialect</span></tt></a> in use.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeDecorator.process_result_value">
<tt class="descname">process_result_value</tt><big>(</big><em>value</em>, <em>dialect</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeDecorator.process_result_value" title="Permalink to this definition">¶</a></dt>
<dd><p>Receive a result-row column value to be converted.</p>
<p>Subclasses should implement this method to operate on data
fetched from the database.</p>
<p>Subclasses override this method to return the
value that should be passed back to the application,
given a value that is already processed by
the underlying <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a> object, originally
from the DBAPI cursor method <tt class="docutils literal"><span class="pre">fetchone()</span></tt> or similar.</p>
<p>The operation could be anything desired to perform custom
behavior, such as transforming or serializing data.
This could also be used as a hook for validating logic.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>value</strong> &#8211; Data to operate upon, of any type expected by
this method in the subclass.  Can be <tt class="docutils literal"><span class="pre">None</span></tt>.</li>
<li><strong>dialect</strong> &#8211; the <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Dialect" title="sqlalchemy.engine.interfaces.Dialect"><tt class="xref py py-class docutils literal"><span class="pre">Dialect</span></tt></a> in use.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>This operation should be designed to be reversible by
the &#8220;process_bind_param&#8221; method of this class.</p>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.types.TypeDecorator.python_type">
<tt class="descname">python_type</tt><a class="headerlink" href="#sqlalchemy.types.TypeDecorator.python_type" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.types.TypeEngine.python_type" title="sqlalchemy.types.TypeEngine.python_type"><tt class="xref py py-attr docutils literal"><span class="pre">python_type</span></tt></a> <em>attribute of</em> <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a></div>
<p>Return the Python type object expected to be returned
by instances of this type, if known.</p>
<p>Basically, for those types which enforce a return type,
or are known across the board to do such for all common
DBAPIs (like <tt class="docutils literal"><span class="pre">int</span></tt> for example), will return that type.</p>
<p>If a return type is not defined, raises
<tt class="docutils literal"><span class="pre">NotImplementedError</span></tt>.</p>
<p>Note that any type also accommodates NULL in SQL which
means you can also get back <tt class="docutils literal"><span class="pre">None</span></tt> from any type
in practice.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeDecorator.result_processor">
<tt class="descname">result_processor</tt><big>(</big><em>dialect</em>, <em>coltype</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeDecorator.result_processor" title="Permalink to this definition">¶</a></dt>
<dd><p>Provide a result value processing function for the given
<a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Dialect" title="sqlalchemy.engine.interfaces.Dialect"><tt class="xref py py-class docutils literal"><span class="pre">Dialect</span></tt></a>.</p>
<p>This is the method that fulfills the <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a>
contract for result value conversion.   <a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">TypeDecorator</span></tt></a>
will wrap a user-defined implementation of
<a class="reference internal" href="#sqlalchemy.types.TypeDecorator.process_result_value" title="sqlalchemy.types.TypeDecorator.process_result_value"><tt class="xref py py-meth docutils literal"><span class="pre">process_result_value()</span></tt></a> here.</p>
<p>User-defined code can override this method directly,
though its likely best to use <a class="reference internal" href="#sqlalchemy.types.TypeDecorator.process_result_value" title="sqlalchemy.types.TypeDecorator.process_result_value"><tt class="xref py py-meth docutils literal"><span class="pre">process_result_value()</span></tt></a> so that
the processing provided by <tt class="docutils literal"><span class="pre">self.impl</span></tt> is maintained.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>dialect</strong> &#8211; Dialect instance in use.</li>
<li><strong>coltype</strong> &#8211; An SQLAlchemy data type</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>This method is the reverse counterpart to the
<a class="reference internal" href="#sqlalchemy.types.TypeDecorator.bind_processor" title="sqlalchemy.types.TypeDecorator.bind_processor"><tt class="xref py py-meth docutils literal"><span class="pre">bind_processor()</span></tt></a> method of this class.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeDecorator.type_engine">
<tt class="descname">type_engine</tt><big>(</big><em>dialect</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeDecorator.type_engine" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a dialect-specific <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a> instance
for this <a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">TypeDecorator</span></tt></a>.</p>
<p>In most cases this returns a dialect-adapted form of
the <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a> type represented by <tt class="docutils literal"><span class="pre">self.impl</span></tt>.
Makes usage of <a class="reference internal" href="#sqlalchemy.types.TypeDecorator.dialect_impl" title="sqlalchemy.types.TypeDecorator.dialect_impl"><tt class="xref py py-meth docutils literal"><span class="pre">dialect_impl()</span></tt></a> but also traverses
into wrapped <a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">TypeDecorator</span></tt></a> instances.
Behavior can be customized here by overriding
<a class="reference internal" href="#sqlalchemy.types.TypeDecorator.load_dialect_impl" title="sqlalchemy.types.TypeDecorator.load_dialect_impl"><tt class="xref py py-meth docutils literal"><span class="pre">load_dialect_impl()</span></tt></a>.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeDecorator.with_variant">
<tt class="descname">with_variant</tt><big>(</big><em>type_</em>, <em>dialect_name</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeDecorator.with_variant" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.types.TypeEngine.with_variant" title="sqlalchemy.types.TypeEngine.with_variant"><tt class="xref py py-meth docutils literal"><span class="pre">with_variant()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a></div>
<p>Produce a new type object that will utilize the given
type when applied to the dialect of the given name.</p>
<p>e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.types</span> <span class="kn">import</span> <span class="n">String</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.dialects</span> <span class="kn">import</span> <span class="n">mysql</span>

<span class="n">s</span> <span class="o">=</span> <span class="n">String</span><span class="p">()</span>

<span class="n">s</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">with_variant</span><span class="p">(</span><span class="n">mysql</span><span class="o">.</span><span class="n">VARCHAR</span><span class="p">(</span><span class="n">collation</span><span class="o">=</span><span class="s">&#39;foo&#39;</span><span class="p">),</span> <span class="s">&#39;mysql&#39;</span><span class="p">)</span></pre></div>
</div>
<p>The construction of <a class="reference internal" href="#sqlalchemy.types.TypeEngine.with_variant" title="sqlalchemy.types.TypeEngine.with_variant"><tt class="xref py py-meth docutils literal"><span class="pre">TypeEngine.with_variant()</span></tt></a> is always
from the &#8220;fallback&#8221; type to that which is dialect specific.
The returned type is an instance of <a class="reference internal" href="#sqlalchemy.types.Variant" title="sqlalchemy.types.Variant"><tt class="xref py py-class docutils literal"><span class="pre">Variant</span></tt></a>, which
itself provides a <a class="reference internal" href="#sqlalchemy.types.Variant.with_variant" title="sqlalchemy.types.Variant.with_variant"><tt class="xref py py-meth docutils literal"><span class="pre">with_variant()</span></tt></a>
that can be called repeatedly.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>type</strong> &#8211; a <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a> that will be selected
as a variant from the originating type, when a dialect
of the given name is in use.</li>
<li><strong>dialect_name</strong> &#8211; base name of the dialect which uses
this type. (i.e. <tt class="docutils literal"><span class="pre">'postgresql'</span></tt>, <tt class="docutils literal"><span class="pre">'mysql'</span></tt>, etc.)</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p class="versionadded">
<span class="versionmodified">New in version 0.7.2.</span></p>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="typedecorator-recipes">
<h3>TypeDecorator Recipes<a class="headerlink" href="#typedecorator-recipes" title="Permalink to this headline">¶</a></h3>
<p>A few key <a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">TypeDecorator</span></tt></a> recipes follow.</p>
<div class="section" id="coercing-encoded-strings-to-unicode">
<span id="coerce-to-unicode"></span><h4>Coercing Encoded Strings to Unicode<a class="headerlink" href="#coercing-encoded-strings-to-unicode" title="Permalink to this headline">¶</a></h4>
<p>A common source of confusion regarding the <a class="reference internal" href="#sqlalchemy.types.Unicode" title="sqlalchemy.types.Unicode"><tt class="xref py py-class docutils literal"><span class="pre">Unicode</span></tt></a> type
is that it is intended to deal <em>only</em> with Python <tt class="docutils literal"><span class="pre">unicode</span></tt> objects
on the Python side, meaning values passed to it as bind parameters
must be of the form <tt class="docutils literal"><span class="pre">u'some</span> <span class="pre">string'</span></tt> if using Python 2 and not 3.
The encoding/decoding functions it performs are only to suit what the
DBAPI in use requires, and are primarily a private implementation detail.</p>
<p>The use case of a type that can safely receive Python bytestrings,
that is strings that contain non-ASCII characters and are not <tt class="docutils literal"><span class="pre">u''</span></tt>
objects in Python 2, can be achieved using a <a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">TypeDecorator</span></tt></a>
which coerces as needed:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.types</span> <span class="kn">import</span> <span class="n">TypeDecorator</span><span class="p">,</span> <span class="n">Unicode</span>

<span class="k">class</span> <span class="nc">CoerceUTF8</span><span class="p">(</span><span class="n">TypeDecorator</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;Safely coerce Python bytestrings to Unicode</span>
<span class="sd">    before passing off to the database.&quot;&quot;&quot;</span>

    <span class="n">impl</span> <span class="o">=</span> <span class="n">Unicode</span>

    <span class="k">def</span> <span class="nf">process_bind_param</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">dialect</span><span class="p">):</span>
        <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="nb">str</span><span class="p">):</span>
            <span class="n">value</span> <span class="o">=</span> <span class="n">value</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s">&#39;utf-8&#39;</span><span class="p">)</span>
        <span class="k">return</span> <span class="n">value</span></pre></div>
</div>
</div>
<div class="section" id="rounding-numerics">
<h4>Rounding Numerics<a class="headerlink" href="#rounding-numerics" title="Permalink to this headline">¶</a></h4>
<p>Some database connectors like those of SQL Server choke if a Decimal is passed with too
many decimal places.   Here&#8217;s a recipe that rounds them down:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.types</span> <span class="kn">import</span> <span class="n">TypeDecorator</span><span class="p">,</span> <span class="n">Numeric</span>
<span class="kn">from</span> <span class="nn">decimal</span> <span class="kn">import</span> <span class="n">Decimal</span>

<span class="k">class</span> <span class="nc">SafeNumeric</span><span class="p">(</span><span class="n">TypeDecorator</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;Adds quantization to Numeric.&quot;&quot;&quot;</span>

    <span class="n">impl</span> <span class="o">=</span> <span class="n">Numeric</span>

    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">*</span><span class="n">arg</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">):</span>
        <span class="n">TypeDecorator</span><span class="o">.</span><span class="n">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">*</span><span class="n">arg</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">)</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">quantize_int</span> <span class="o">=</span> <span class="o">-</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">impl</span><span class="o">.</span><span class="n">precision</span> <span class="o">-</span> <span class="bp">self</span><span class="o">.</span><span class="n">impl</span><span class="o">.</span><span class="n">scale</span><span class="p">)</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">quantize</span> <span class="o">=</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span> <span class="o">**</span> <span class="bp">self</span><span class="o">.</span><span class="n">quantize_int</span>

    <span class="k">def</span> <span class="nf">process_bind_param</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">dialect</span><span class="p">):</span>
        <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="n">Decimal</span><span class="p">)</span> <span class="ow">and</span> \
            <span class="n">value</span><span class="o">.</span><span class="n">as_tuple</span><span class="p">()[</span><span class="mi">2</span><span class="p">]</span> <span class="o">&lt;</span> <span class="bp">self</span><span class="o">.</span><span class="n">quantize_int</span><span class="p">:</span>
            <span class="n">value</span> <span class="o">=</span> <span class="n">value</span><span class="o">.</span><span class="n">quantize</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">quantize</span><span class="p">)</span>
        <span class="k">return</span> <span class="n">value</span></pre></div>
</div>
</div>
<div class="section" id="backend-agnostic-guid-type">
<h4>Backend-agnostic GUID Type<a class="headerlink" href="#backend-agnostic-guid-type" title="Permalink to this headline">¶</a></h4>
<p>Receives and returns Python uuid() objects.  Uses the PG UUID type
when using Postgresql, CHAR(32) on other backends, storing them
in stringified hex format.   Can be modified to store
binary in CHAR(16) if desired:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.types</span> <span class="kn">import</span> <span class="n">TypeDecorator</span><span class="p">,</span> <span class="n">CHAR</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.dialects.postgresql</span> <span class="kn">import</span> <span class="n">UUID</span>
<span class="kn">import</span> <span class="nn">uuid</span>

<span class="k">class</span> <span class="nc">GUID</span><span class="p">(</span><span class="n">TypeDecorator</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;Platform-independent GUID type.</span>

<span class="sd">    Uses Postgresql&#39;s UUID type, otherwise uses</span>
<span class="sd">    CHAR(32), storing as stringified hex values.</span>

<span class="sd">    &quot;&quot;&quot;</span>
    <span class="n">impl</span> <span class="o">=</span> <span class="n">CHAR</span>

    <span class="k">def</span> <span class="nf">load_dialect_impl</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dialect</span><span class="p">):</span>
        <span class="k">if</span> <span class="n">dialect</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s">&#39;postgresql&#39;</span><span class="p">:</span>
            <span class="k">return</span> <span class="n">dialect</span><span class="o">.</span><span class="n">type_descriptor</span><span class="p">(</span><span class="n">UUID</span><span class="p">())</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="k">return</span> <span class="n">dialect</span><span class="o">.</span><span class="n">type_descriptor</span><span class="p">(</span><span class="n">CHAR</span><span class="p">(</span><span class="mi">32</span><span class="p">))</span>

    <span class="k">def</span> <span class="nf">process_bind_param</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">dialect</span><span class="p">):</span>
        <span class="k">if</span> <span class="n">value</span> <span class="ow">is</span> <span class="bp">None</span><span class="p">:</span>
            <span class="k">return</span> <span class="n">value</span>
        <span class="k">elif</span> <span class="n">dialect</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s">&#39;postgresql&#39;</span><span class="p">:</span>
            <span class="k">return</span> <span class="nb">str</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="n">uuid</span><span class="o">.</span><span class="n">UUID</span><span class="p">):</span>
                <span class="k">return</span> <span class="s">&quot;</span><span class="si">%.32x</span><span class="s">&quot;</span> <span class="o">%</span> <span class="n">uuid</span><span class="o">.</span><span class="n">UUID</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
            <span class="k">else</span><span class="p">:</span>
                <span class="c"># hexstring</span>
                <span class="k">return</span> <span class="s">&quot;</span><span class="si">%.32x</span><span class="s">&quot;</span> <span class="o">%</span> <span class="n">value</span>

    <span class="k">def</span> <span class="nf">process_result_value</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">dialect</span><span class="p">):</span>
        <span class="k">if</span> <span class="n">value</span> <span class="ow">is</span> <span class="bp">None</span><span class="p">:</span>
            <span class="k">return</span> <span class="n">value</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="k">return</span> <span class="n">uuid</span><span class="o">.</span><span class="n">UUID</span><span class="p">(</span><span class="n">value</span><span class="p">)</span></pre></div>
</div>
</div>
<div class="section" id="marshal-json-strings">
<h4>Marshal JSON Strings<a class="headerlink" href="#marshal-json-strings" title="Permalink to this headline">¶</a></h4>
<p>This type uses <tt class="docutils literal"><span class="pre">simplejson</span></tt> to marshal Python data structures
to/from JSON.   Can be modified to use Python&#8217;s builtin json encoder:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.types</span> <span class="kn">import</span> <span class="n">TypeDecorator</span><span class="p">,</span> <span class="n">VARCHAR</span>
<span class="kn">import</span> <span class="nn">json</span>

<span class="k">class</span> <span class="nc">JSONEncodedDict</span><span class="p">(</span><span class="n">TypeDecorator</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;Represents an immutable structure as a json-encoded string.</span>

<span class="sd">    Usage::</span>

<span class="sd">        JSONEncodedDict(255)</span>

<span class="sd">    &quot;&quot;&quot;</span>

    <span class="n">impl</span> <span class="o">=</span> <span class="n">VARCHAR</span>

    <span class="k">def</span> <span class="nf">process_bind_param</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">dialect</span><span class="p">):</span>
        <span class="k">if</span> <span class="n">value</span> <span class="ow">is</span> <span class="ow">not</span> <span class="bp">None</span><span class="p">:</span>
            <span class="n">value</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">dumps</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>

        <span class="k">return</span> <span class="n">value</span>

    <span class="k">def</span> <span class="nf">process_result_value</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">dialect</span><span class="p">):</span>
        <span class="k">if</span> <span class="n">value</span> <span class="ow">is</span> <span class="ow">not</span> <span class="bp">None</span><span class="p">:</span>
            <span class="n">value</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
        <span class="k">return</span> <span class="n">value</span></pre></div>
</div>
<p>Note that the ORM by default will not detect &#8220;mutability&#8221; on such a type -
meaning, in-place changes to values will not be detected and will not be
flushed. Without further steps, you instead would need to replace the existing
value with a new one on each parent object to detect changes. Note that
there&#8217;s nothing wrong with this, as many applications may not require that the
values are ever mutated once created.  For those which do have this requirment,
support for mutability is best applied using the <tt class="docutils literal"><span class="pre">sqlalchemy.ext.mutable</span></tt>
extension - see the example in <a class="reference internal" href="../orm/extensions/mutable.html"><em>Mutation Tracking</em></a>.</p>
</div>
</div>
<div class="section" id="replacing-the-bind-result-processing-of-existing-types">
<span id="replacing-processors"></span><h3>Replacing the Bind/Result Processing of Existing Types<a class="headerlink" href="#replacing-the-bind-result-processing-of-existing-types" title="Permalink to this headline">¶</a></h3>
<p>Most augmentation of type behavior at the bind/result level
is achieved using <a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">TypeDecorator</span></tt></a>.   For the rare scenario
where the specific processing applied by SQLAlchemy at the DBAPI
level needs to be replaced, the SQLAlchemy type can be subclassed
directly, and the <tt class="docutils literal"><span class="pre">bind_processor()</span></tt> or <tt class="docutils literal"><span class="pre">result_processor()</span></tt>
methods can be overridden.   Doing so requires that the
<tt class="docutils literal"><span class="pre">adapt()</span></tt> method also be overridden.  This method is the mechanism
by which SQLAlchemy produces DBAPI-specific type behavior during
statement execution.  Overriding it allows a copy of the custom
type to be used in lieu of a DBAPI-specific type.  Below we subclass
the <a class="reference internal" href="#sqlalchemy.types.TIME" title="sqlalchemy.types.TIME"><tt class="xref py py-class docutils literal"><span class="pre">types.TIME</span></tt></a> type to have custom result processing behavior.
The <tt class="docutils literal"><span class="pre">process()</span></tt> function will receive <tt class="docutils literal"><span class="pre">value</span></tt> from the DBAPI
cursor directly:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MySpecialTime</span><span class="p">(</span><span class="n">TIME</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">special_argument</span><span class="p">):</span>
        <span class="nb">super</span><span class="p">(</span><span class="n">MySpecialTime</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">__init__</span><span class="p">()</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">special_argument</span> <span class="o">=</span> <span class="n">special_argument</span>

    <span class="k">def</span> <span class="nf">result_processor</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dialect</span><span class="p">,</span> <span class="n">coltype</span><span class="p">):</span>
        <span class="kn">import</span> <span class="nn">datetime</span>
        <span class="n">time</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">time</span>
        <span class="k">def</span> <span class="nf">process</span><span class="p">(</span><span class="n">value</span><span class="p">):</span>
            <span class="k">if</span> <span class="n">value</span> <span class="ow">is</span> <span class="ow">not</span> <span class="bp">None</span><span class="p">:</span>
                <span class="n">microseconds</span> <span class="o">=</span> <span class="n">value</span><span class="o">.</span><span class="n">microseconds</span>
                <span class="n">seconds</span> <span class="o">=</span> <span class="n">value</span><span class="o">.</span><span class="n">seconds</span>
                <span class="n">minutes</span> <span class="o">=</span> <span class="n">seconds</span> <span class="o">/</span> <span class="mi">60</span>
                <span class="k">return</span> <span class="n">time</span><span class="p">(</span>
                          <span class="n">minutes</span> <span class="o">/</span> <span class="mi">60</span><span class="p">,</span>
                          <span class="n">minutes</span> <span class="o">%</span> <span class="mi">60</span><span class="p">,</span>
                          <span class="n">seconds</span> <span class="o">-</span> <span class="n">minutes</span> <span class="o">*</span> <span class="mi">60</span><span class="p">,</span>
                          <span class="n">microseconds</span><span class="p">)</span>
            <span class="k">else</span><span class="p">:</span>
                <span class="k">return</span> <span class="bp">None</span>
        <span class="k">return</span> <span class="n">process</span>

    <span class="k">def</span> <span class="nf">adapt</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">impltype</span><span class="p">):</span>
        <span class="k">return</span> <span class="n">MySpecialTime</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">special_argument</span><span class="p">)</span></pre></div>
</div>
</div>
<div class="section" id="applying-sql-level-bind-result-processing">
<span id="types-sql-value-processing"></span><h3>Applying SQL-level Bind/Result Processing<a class="headerlink" href="#applying-sql-level-bind-result-processing" title="Permalink to this headline">¶</a></h3>
<p>As seen in the sections <a class="reference internal" href="#types-typedecorator"><em>Augmenting Existing Types</em></a> and <a class="reference internal" href="#replacing-processors"><em>Replacing the Bind/Result Processing of Existing Types</em></a>,
SQLAlchemy allows Python functions to be invoked both when parameters are sent
to a statement, as well as when result rows are loaded from the database, to apply
transformations to the values as they are sent to or from the database.   It is also
possible to define SQL-level transformations as well.  The rationale here is when
only the relational database contains a particular series of functions that are necessary
to coerce incoming and outgoing data between an application and persistence format.
Examples include using database-defined encryption/decryption functions, as well
as stored procedures that handle geographic data.  The Postgis extension to Postgresql
includes an extensive array of SQL functions that are necessary for coercing
data into particular formats.</p>
<p>Any <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a>, <a class="reference internal" href="#sqlalchemy.types.UserDefinedType" title="sqlalchemy.types.UserDefinedType"><tt class="xref py py-class docutils literal"><span class="pre">UserDefinedType</span></tt></a> or <a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">TypeDecorator</span></tt></a> subclass
can include implementations of
<a class="reference internal" href="#sqlalchemy.types.TypeEngine.bind_expression" title="sqlalchemy.types.TypeEngine.bind_expression"><tt class="xref py py-meth docutils literal"><span class="pre">TypeEngine.bind_expression()</span></tt></a> and/or <a class="reference internal" href="#sqlalchemy.types.TypeEngine.column_expression" title="sqlalchemy.types.TypeEngine.column_expression"><tt class="xref py py-meth docutils literal"><span class="pre">TypeEngine.column_expression()</span></tt></a>, which
when defined to return a non-<tt class="docutils literal"><span class="pre">None</span></tt> value should return a <a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a>
expression to be injected into the SQL statement, either surrounding
bound parameters or a column expression.  For example, to build a <tt class="docutils literal"><span class="pre">Geometry</span></tt>
type which will apply the Postgis function <tt class="docutils literal"><span class="pre">ST_GeomFromText</span></tt> to all outgoing
values and the function <tt class="docutils literal"><span class="pre">ST_AsText</span></tt> to all incoming data, we can create
our own subclass of <a class="reference internal" href="#sqlalchemy.types.UserDefinedType" title="sqlalchemy.types.UserDefinedType"><tt class="xref py py-class docutils literal"><span class="pre">UserDefinedType</span></tt></a> which provides these methods
in conjunction with <a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.func" title="sqlalchemy.sql.expression.func"><tt class="xref py py-data docutils literal"><span class="pre">func</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">func</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.types</span> <span class="kn">import</span> <span class="n">UserDefinedType</span>

<span class="k">class</span> <span class="nc">Geometry</span><span class="p">(</span><span class="n">UserDefinedType</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">get_col_spec</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="s">&quot;GEOMETRY&quot;</span>

    <span class="k">def</span> <span class="nf">bind_expression</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">bindvalue</span><span class="p">):</span>
        <span class="k">return</span> <span class="n">func</span><span class="o">.</span><span class="n">ST_GeomFromText</span><span class="p">(</span><span class="n">bindvalue</span><span class="p">,</span> <span class="n">type_</span><span class="o">=</span><span class="bp">self</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">column_expression</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">col</span><span class="p">):</span>
        <span class="k">return</span> <span class="n">func</span><span class="o">.</span><span class="n">ST_AsText</span><span class="p">(</span><span class="n">col</span><span class="p">,</span> <span class="n">type_</span><span class="o">=</span><span class="bp">self</span><span class="p">)</span></pre></div>
</div>
<p>We can apply the <tt class="docutils literal"><span class="pre">Geometry</span></tt> type into <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> metadata
and use it in a <a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal"><span class="pre">select()</span></tt></a> construct:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">geometry</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s">&#39;geometry&#39;</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span>
              <span class="n">Column</span><span class="p">(</span><span class="s">&#39;geom_id&#39;</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">),</span>
              <span class="n">Column</span><span class="p">(</span><span class="s">&#39;geom_data&#39;</span><span class="p">,</span> <span class="n">Geometry</span><span class="p">)</span>
            <span class="p">)</span>

<span class="k">print</span> <span class="n">select</span><span class="p">([</span><span class="n">geometry</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span>
  <span class="n">geometry</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">geom_data</span> <span class="o">==</span> <span class="s">&#39;LINESTRING(189412 252431,189631 259122)&#39;</span><span class="p">)</span></pre></div>
</div>
<p>The resulting SQL embeds both functions as appropriate.   <tt class="docutils literal"><span class="pre">ST_AsText</span></tt>
is applied to the columns clause so that the return value is run through
the function before passing into a result set, and <tt class="docutils literal"><span class="pre">ST_GeomFromText</span></tt>
is run on the bound parameter so that the passed-in value is converted:</p>
<div class="highlight-python"><pre>SELECT geometry.geom_id, ST_AsText(geometry.geom_data) AS geom_data_1
FROM geometry
WHERE geometry.geom_data = ST_GeomFromText(:geom_data_2)</pre>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.types.TypeEngine.column_expression" title="sqlalchemy.types.TypeEngine.column_expression"><tt class="xref py py-meth docutils literal"><span class="pre">TypeEngine.column_expression()</span></tt></a> method interacts with the
mechanics of the compiler such that the SQL expression does not interfere
with the labeling of the wrapped expression.   Such as, if we rendered
a <a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal"><span class="pre">select()</span></tt></a> against a <a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.label" title="sqlalchemy.sql.expression.label"><tt class="xref py py-func docutils literal"><span class="pre">label()</span></tt></a> of our expression, the string
label is moved to the outside of the wrapped expression:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">print</span> <span class="n">select</span><span class="p">([</span><span class="n">geometry</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">geom_data</span><span class="o">.</span><span class="n">label</span><span class="p">(</span><span class="s">&#39;my_data&#39;</span><span class="p">)])</span></pre></div>
</div>
<p>Output:</p>
<div class="highlight-python"><pre>SELECT ST_AsText(geometry.geom_data) AS my_data
FROM geometry</pre>
</div>
<p>For an example of subclassing a built in type directly, we subclass
<a class="reference internal" href="../dialects/postgresql.html#sqlalchemy.dialects.postgresql.BYTEA" title="sqlalchemy.dialects.postgresql.BYTEA"><tt class="xref py py-class docutils literal"><span class="pre">postgresql.BYTEA</span></tt></a> to provide a <tt class="docutils literal"><span class="pre">PGPString</span></tt>, which will make use of the
Postgresql <tt class="docutils literal"><span class="pre">pgcrypto</span></tt> extension to encrpyt/decrypt values
transparently:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">create_engine</span><span class="p">,</span> <span class="n">String</span><span class="p">,</span> <span class="n">select</span><span class="p">,</span> <span class="n">func</span><span class="p">,</span> \
        <span class="n">MetaData</span><span class="p">,</span> <span class="n">Table</span><span class="p">,</span> <span class="n">Column</span><span class="p">,</span> <span class="n">type_coerce</span>

<span class="kn">from</span> <span class="nn">sqlalchemy.dialects.postgresql</span> <span class="kn">import</span> <span class="n">BYTEA</span>

<span class="k">class</span> <span class="nc">PGPString</span><span class="p">(</span><span class="n">BYTEA</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">passphrase</span><span class="p">,</span> <span class="n">length</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
        <span class="nb">super</span><span class="p">(</span><span class="n">PGPString</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">__init__</span><span class="p">(</span><span class="n">length</span><span class="p">)</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">passphrase</span> <span class="o">=</span> <span class="n">passphrase</span>

    <span class="k">def</span> <span class="nf">bind_expression</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">bindvalue</span><span class="p">):</span>
        <span class="c"># convert the bind&#39;s type from PGPString to</span>
        <span class="c"># String, so that it&#39;s passed to psycopg2 as is without</span>
        <span class="c"># a dbapi.Binary wrapper</span>
        <span class="n">bindvalue</span> <span class="o">=</span> <span class="n">type_coerce</span><span class="p">(</span><span class="n">bindvalue</span><span class="p">,</span> <span class="n">String</span><span class="p">)</span>
        <span class="k">return</span> <span class="n">func</span><span class="o">.</span><span class="n">pgp_sym_encrypt</span><span class="p">(</span><span class="n">bindvalue</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">passphrase</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">column_expression</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">col</span><span class="p">):</span>
        <span class="k">return</span> <span class="n">func</span><span class="o">.</span><span class="n">pgp_sym_decrypt</span><span class="p">(</span><span class="n">col</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">passphrase</span><span class="p">)</span>

<span class="n">metadata</span> <span class="o">=</span> <span class="n">MetaData</span><span class="p">()</span>
<span class="n">message</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s">&#39;message&#39;</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span>
                <span class="n">Column</span><span class="p">(</span><span class="s">&#39;username&#39;</span><span class="p">,</span> <span class="n">String</span><span class="p">(</span><span class="mi">50</span><span class="p">)),</span>
                <span class="n">Column</span><span class="p">(</span><span class="s">&#39;message&#39;</span><span class="p">,</span>
                    <span class="n">PGPString</span><span class="p">(</span><span class="s">&quot;this is my passphrase&quot;</span><span class="p">,</span> <span class="n">length</span><span class="o">=</span><span class="mi">1000</span><span class="p">)),</span>
            <span class="p">)</span>

<span class="n">engine</span> <span class="o">=</span> <span class="n">create_engine</span><span class="p">(</span><span class="s">&quot;postgresql://scott:tiger@localhost/test&quot;</span><span class="p">,</span> <span class="n">echo</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="k">with</span> <span class="n">engine</span><span class="o">.</span><span class="n">begin</span><span class="p">()</span> <span class="k">as</span> <span class="n">conn</span><span class="p">:</span>
    <span class="n">metadata</span><span class="o">.</span><span class="n">create_all</span><span class="p">(</span><span class="n">conn</span><span class="p">)</span>

    <span class="n">conn</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">message</span><span class="o">.</span><span class="n">insert</span><span class="p">(),</span> <span class="n">username</span><span class="o">=</span><span class="s">&quot;some user&quot;</span><span class="p">,</span>
                                <span class="n">message</span><span class="o">=</span><span class="s">&quot;this is my message&quot;</span><span class="p">)</span>

    <span class="k">print</span> <span class="n">conn</span><span class="o">.</span><span class="n">scalar</span><span class="p">(</span>
            <span class="n">select</span><span class="p">([</span><span class="n">message</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">message</span><span class="p">])</span><span class="o">.</span>\
                <span class="n">where</span><span class="p">(</span><span class="n">message</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">username</span> <span class="o">==</span> <span class="s">&quot;some user&quot;</span><span class="p">)</span>
        <span class="p">)</span></pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">pgp_sym_encrypt</span></tt> and <tt class="docutils literal"><span class="pre">pgp_sym_decrypt</span></tt> functions are applied
to the INSERT and SELECT statements:</p>
<div class="highlight-python"><pre>INSERT INTO message (username, message)
  VALUES (%(username)s, pgp_sym_encrypt(%(message)s, %(pgp_sym_encrypt_1)s))
  {'username': 'some user', 'message': 'this is my message',
    'pgp_sym_encrypt_1': 'this is my passphrase'}

SELECT pgp_sym_decrypt(message.message, %(pgp_sym_decrypt_1)s) AS message_1
  FROM message
  WHERE message.username = %(username_1)s
  {'pgp_sym_decrypt_1': 'this is my passphrase', 'username_1': 'some user'}</pre>
</div>
<p class="versionadded">
<span class="versionmodified">New in version 0.8: </span>Added the <a class="reference internal" href="#sqlalchemy.types.TypeEngine.bind_expression" title="sqlalchemy.types.TypeEngine.bind_expression"><tt class="xref py py-meth docutils literal"><span class="pre">TypeEngine.bind_expression()</span></tt></a> and
<a class="reference internal" href="#sqlalchemy.types.TypeEngine.column_expression" title="sqlalchemy.types.TypeEngine.column_expression"><tt class="xref py py-meth docutils literal"><span class="pre">TypeEngine.column_expression()</span></tt></a> methods.</p>
<p>See also:</p>
<p><a class="reference internal" href="../orm/examples.html#examples-postgis"><em>PostGIS Integration</em></a></p>
</div>
<div class="section" id="redefining-and-creating-new-operators">
<span id="types-operators"></span><h3>Redefining and Creating New Operators<a class="headerlink" href="#redefining-and-creating-new-operators" title="Permalink to this headline">¶</a></h3>
<p>SQLAlchemy Core defines a fixed set of expression operators available to all column expressions.
Some of these operations have the effect of overloading Python&#8217;s built in operators;
examples of such operators include
<a class="reference internal" href="expression_api.html#sqlalchemy.sql.operators.ColumnOperators.__eq__" title="sqlalchemy.sql.operators.ColumnOperators.__eq__"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.__eq__()</span></tt></a> (<tt class="docutils literal"><span class="pre">table.c.somecolumn</span> <span class="pre">==</span> <span class="pre">'foo'</span></tt>),
<a class="reference internal" href="expression_api.html#sqlalchemy.sql.operators.ColumnOperators.__invert__" title="sqlalchemy.sql.operators.ColumnOperators.__invert__"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.__invert__()</span></tt></a> (<tt class="docutils literal"><span class="pre">~table.c.flag</span></tt>),
and <a class="reference internal" href="expression_api.html#sqlalchemy.sql.operators.ColumnOperators.__add__" title="sqlalchemy.sql.operators.ColumnOperators.__add__"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.__add__()</span></tt></a> (<tt class="docutils literal"><span class="pre">table.c.x</span> <span class="pre">+</span> <span class="pre">table.c.y</span></tt>).  Other operators are exposed as
explicit methods on column expressions, such as
<a class="reference internal" href="expression_api.html#sqlalchemy.sql.operators.ColumnOperators.in_" title="sqlalchemy.sql.operators.ColumnOperators.in_"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.in_()</span></tt></a> (<tt class="docutils literal"><span class="pre">table.c.value.in_(['x',</span> <span class="pre">'y'])</span></tt>) and <a class="reference internal" href="expression_api.html#sqlalchemy.sql.operators.ColumnOperators.like" title="sqlalchemy.sql.operators.ColumnOperators.like"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.like()</span></tt></a>
(<tt class="docutils literal"><span class="pre">table.c.value.like('%ed%')</span></tt>).</p>
<p>The Core expression constructs in all cases consult the type of the expression in order to determine
the behavior of existing operators, as well as to locate additional operators that aren&#8217;t part of
the built in set.   The <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a> base class defines a root &#8220;comparison&#8221; implementation
<a class="reference internal" href="#sqlalchemy.types.TypeEngine.Comparator" title="sqlalchemy.types.TypeEngine.Comparator"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine.Comparator</span></tt></a>, and many specific types provide their own sub-implementations of this
class.   User-defined <a class="reference internal" href="#sqlalchemy.types.TypeEngine.Comparator" title="sqlalchemy.types.TypeEngine.Comparator"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine.Comparator</span></tt></a> implementations can be built directly into a
simple subclass of a particular type in order to override or define new operations.  Below,
we create a <a class="reference internal" href="#sqlalchemy.types.Integer" title="sqlalchemy.types.Integer"><tt class="xref py py-class docutils literal"><span class="pre">Integer</span></tt></a> subclass which overrides the <a class="reference internal" href="expression_api.html#sqlalchemy.sql.operators.ColumnOperators.__add__" title="sqlalchemy.sql.operators.ColumnOperators.__add__"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.__add__()</span></tt></a> operator:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">Integer</span>

<span class="k">class</span> <span class="nc">MyInt</span><span class="p">(</span><span class="n">Integer</span><span class="p">):</span>
    <span class="k">class</span> <span class="nc">comparator_factory</span><span class="p">(</span><span class="n">Integer</span><span class="o">.</span><span class="n">Comparator</span><span class="p">):</span>
        <span class="k">def</span> <span class="nf">__add__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">op</span><span class="p">(</span><span class="s">&quot;goofy&quot;</span><span class="p">)(</span><span class="n">other</span><span class="p">)</span></pre></div>
</div>
<p>The above configuration creates a new class <tt class="docutils literal"><span class="pre">MyInt</span></tt>, which
establishes the <a class="reference internal" href="#sqlalchemy.types.TypeEngine.comparator_factory" title="sqlalchemy.types.TypeEngine.comparator_factory"><tt class="xref py py-attr docutils literal"><span class="pre">TypeEngine.comparator_factory</span></tt></a> attribute as
referring to a new class, subclassing the <a class="reference internal" href="#sqlalchemy.types.TypeEngine.Comparator" title="sqlalchemy.types.TypeEngine.Comparator"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine.Comparator</span></tt></a> class
associated with the <a class="reference internal" href="#sqlalchemy.types.Integer" title="sqlalchemy.types.Integer"><tt class="xref py py-class docutils literal"><span class="pre">Integer</span></tt></a> type.</p>
<p>Usage:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">sometable</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s">&quot;sometable&quot;</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span> <span class="n">Column</span><span class="p">(</span><span class="s">&quot;data&quot;</span><span class="p">,</span> <span class="n">MyInt</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">sometable</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">data</span> <span class="o">+</span> <span class="mi">5</span>
<span class="go">sometable.data goofy :data_1</span></pre></div>
</div>
<p>The implementation for <a class="reference internal" href="expression_api.html#sqlalchemy.sql.operators.ColumnOperators.__add__" title="sqlalchemy.sql.operators.ColumnOperators.__add__"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.__add__()</span></tt></a> is consulted
by an owning SQL expression, by instantiating the <a class="reference internal" href="#sqlalchemy.types.TypeEngine.Comparator" title="sqlalchemy.types.TypeEngine.Comparator"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine.Comparator</span></tt></a> with
itself as the <tt class="docutils literal"><span class="pre">expr</span></tt> attribute.   The mechanics of the expression
system are such that operations continue recursively until an
expression object produces a new SQL expression construct. Above, we
could just as well have said <tt class="docutils literal"><span class="pre">self.expr.op(&quot;goofy&quot;)(other)</span></tt> instead
of <tt class="docutils literal"><span class="pre">self.op(&quot;goofy&quot;)(other)</span></tt>.</p>
<p>New methods added to a <a class="reference internal" href="#sqlalchemy.types.TypeEngine.Comparator" title="sqlalchemy.types.TypeEngine.Comparator"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine.Comparator</span></tt></a> are exposed on an
owning SQL expression
using a <tt class="docutils literal"><span class="pre">__getattr__</span></tt> scheme, which exposes methods added to
<a class="reference internal" href="#sqlalchemy.types.TypeEngine.Comparator" title="sqlalchemy.types.TypeEngine.Comparator"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine.Comparator</span></tt></a> onto the owning <a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a>.
For example, to add a <tt class="docutils literal"><span class="pre">log()</span></tt> function
to integers:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">func</span>

<span class="k">class</span> <span class="nc">MyInt</span><span class="p">(</span><span class="n">Integer</span><span class="p">):</span>
    <span class="k">class</span> <span class="nc">comparator_factory</span><span class="p">(</span><span class="n">Integer</span><span class="o">.</span><span class="n">Comparator</span><span class="p">):</span>
        <span class="k">def</span> <span class="nf">log</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
            <span class="k">return</span> <span class="n">func</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">)</span></pre></div>
</div>
<p>Using the above type:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">sometable</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">data</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
<span class="go">log(:log_1, :log_2)</span></pre></div>
</div>
<p>Unary operations
are also possible.  For example, to add an implementation of the
Postgresql factorial operator, we combine the <a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.UnaryExpression" title="sqlalchemy.sql.expression.UnaryExpression"><tt class="xref py py-class docutils literal"><span class="pre">UnaryExpression</span></tt></a> construct
along with a <a class="reference internal" href="expression_api.html#sqlalchemy.sql.operators.custom_op" title="sqlalchemy.sql.operators.custom_op"><tt class="xref py py-class docutils literal"><span class="pre">custom_op</span></tt></a> to produce the factorial expression:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">Integer</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.sql.expression</span> <span class="kn">import</span> <span class="n">UnaryExpression</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.sql</span> <span class="kn">import</span> <span class="n">operators</span>

<span class="k">class</span> <span class="nc">MyInteger</span><span class="p">(</span><span class="n">Integer</span><span class="p">):</span>
    <span class="k">class</span> <span class="nc">comparator_factory</span><span class="p">(</span><span class="n">Integer</span><span class="o">.</span><span class="n">Comparator</span><span class="p">):</span>
        <span class="k">def</span> <span class="nf">factorial</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
            <span class="k">return</span> <span class="n">UnaryExpression</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">expr</span><span class="p">,</span>
                        <span class="n">modifier</span><span class="o">=</span><span class="n">operators</span><span class="o">.</span><span class="n">custom_op</span><span class="p">(</span><span class="s">&quot;!&quot;</span><span class="p">),</span>
                        <span class="n">type_</span><span class="o">=</span><span class="n">MyInteger</span><span class="p">)</span></pre></div>
</div>
<p>Using the above type:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">sqlalchemy.sql</span> <span class="kn">import</span> <span class="n">column</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">column</span><span class="p">(</span><span class="s">&#39;x&#39;</span><span class="p">,</span> <span class="n">MyInteger</span><span class="p">)</span><span class="o">.</span><span class="n">factorial</span><span class="p">()</span>
<span class="go">x !</span></pre></div>
</div>
<p>See also:</p>
<p><a class="reference internal" href="#sqlalchemy.types.TypeEngine.comparator_factory" title="sqlalchemy.types.TypeEngine.comparator_factory"><tt class="xref py py-attr docutils literal"><span class="pre">TypeEngine.comparator_factory</span></tt></a></p>
<p class="versionadded">
<span class="versionmodified">New in version 0.8: </span>The expression system was enhanced to support
customization of operators on a per-type level.</p>
</div>
<div class="section" id="creating-new-types">
<h3>Creating New Types<a class="headerlink" href="#creating-new-types" title="Permalink to this headline">¶</a></h3>
<p>The <a class="reference internal" href="#sqlalchemy.types.UserDefinedType" title="sqlalchemy.types.UserDefinedType"><tt class="xref py py-class docutils literal"><span class="pre">UserDefinedType</span></tt></a> class is provided as a simple base class
for defining entirely new database types.   Use this to represent native
database types not known by SQLAlchemy.   If only Python translation behavior
is needed, use <a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">TypeDecorator</span></tt></a> instead.</p>
<dl class="class">
<dt id="sqlalchemy.types.UserDefinedType">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">UserDefinedType</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.UserDefinedType" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.TypeEngine</span></tt></a></p>
<p>Base for user defined types.</p>
<p>This should be the base of new types.  Note that
for most cases, <a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">TypeDecorator</span></tt></a> is probably
more appropriate:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">sqlalchemy.types</span> <span class="kn">as</span> <span class="nn">types</span>

<span class="k">class</span> <span class="nc">MyType</span><span class="p">(</span><span class="n">types</span><span class="o">.</span><span class="n">UserDefinedType</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">precision</span> <span class="o">=</span> <span class="mi">8</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">precision</span> <span class="o">=</span> <span class="n">precision</span>

    <span class="k">def</span> <span class="nf">get_col_spec</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="s">&quot;MYTYPE(</span><span class="si">%s</span><span class="s">)&quot;</span> <span class="o">%</span> <span class="bp">self</span><span class="o">.</span><span class="n">precision</span>

    <span class="k">def</span> <span class="nf">bind_processor</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dialect</span><span class="p">):</span>
        <span class="k">def</span> <span class="nf">process</span><span class="p">(</span><span class="n">value</span><span class="p">):</span>
            <span class="k">return</span> <span class="n">value</span>
        <span class="k">return</span> <span class="n">process</span>

    <span class="k">def</span> <span class="nf">result_processor</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dialect</span><span class="p">,</span> <span class="n">coltype</span><span class="p">):</span>
        <span class="k">def</span> <span class="nf">process</span><span class="p">(</span><span class="n">value</span><span class="p">):</span>
            <span class="k">return</span> <span class="n">value</span>
        <span class="k">return</span> <span class="n">process</span></pre></div>
</div>
<p>Once the type is made, it&#8217;s immediately usable:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">table</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s">&#39;foo&#39;</span><span class="p">,</span> <span class="n">meta</span><span class="p">,</span>
    <span class="n">Column</span><span class="p">(</span><span class="s">&#39;id&#39;</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">),</span>
    <span class="n">Column</span><span class="p">(</span><span class="s">&#39;data&#39;</span><span class="p">,</span> <span class="n">MyType</span><span class="p">(</span><span class="mi">16</span><span class="p">))</span>
    <span class="p">)</span></pre></div>
</div>
<dl class="method">
<dt id="sqlalchemy.types.UserDefinedType.coerce_compared_value">
<tt class="descname">coerce_compared_value</tt><big>(</big><em>op</em>, <em>value</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.UserDefinedType.coerce_compared_value" title="Permalink to this definition">¶</a></dt>
<dd><p>Suggest a type for a &#8216;coerced&#8217; Python value in an expression.</p>
<p>Default behavior for <a class="reference internal" href="#sqlalchemy.types.UserDefinedType" title="sqlalchemy.types.UserDefinedType"><tt class="xref py py-class docutils literal"><span class="pre">UserDefinedType</span></tt></a> is the
same as that of <a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">TypeDecorator</span></tt></a>; by default it returns
<tt class="docutils literal"><span class="pre">self</span></tt>, assuming the compared value should be coerced into
the same type as this one.  See
<a class="reference internal" href="#sqlalchemy.types.TypeDecorator.coerce_compared_value" title="sqlalchemy.types.TypeDecorator.coerce_compared_value"><tt class="xref py py-meth docutils literal"><span class="pre">TypeDecorator.coerce_compared_value()</span></tt></a> for more detail.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 0.8: </span><a class="reference internal" href="#sqlalchemy.types.UserDefinedType.coerce_compared_value" title="sqlalchemy.types.UserDefinedType.coerce_compared_value"><tt class="xref py py-meth docutils literal"><span class="pre">UserDefinedType.coerce_compared_value()</span></tt></a>
now returns <tt class="docutils literal"><span class="pre">self</span></tt> by default, rather than falling onto the
more fundamental behavior of
<a class="reference internal" href="#sqlalchemy.types.TypeEngine.coerce_compared_value" title="sqlalchemy.types.TypeEngine.coerce_compared_value"><tt class="xref py py-meth docutils literal"><span class="pre">TypeEngine.coerce_compared_value()</span></tt></a>.</p>
</dd></dl>

</dd></dl>

</div>
</div>
<div class="section" id="base-type-api">
<span id="types-api"></span><h2>Base Type API<a class="headerlink" href="#base-type-api" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="sqlalchemy.types.AbstractType">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">AbstractType</tt><a class="headerlink" href="#sqlalchemy.types.AbstractType" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.visitors.Visitable</span></tt></p>
<p>Base for all types - not needed except for backwards
compatibility.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.TypeEngine">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">TypeEngine</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeEngine" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.AbstractType" title="sqlalchemy.types.AbstractType"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.AbstractType</span></tt></a></p>
<p>Base for built-in types.</p>
<dl class="class">
<dt id="sqlalchemy.types.TypeEngine.Comparator">
<em class="property">class </em><tt class="descname">Comparator</tt><big>(</big><em>expr</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeEngine.Comparator" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression._DefaultColumnComparator</span></tt></p>
<p>Base class for custom comparison operations defined at the
type level.  See <a class="reference internal" href="#sqlalchemy.types.TypeEngine.comparator_factory" title="sqlalchemy.types.TypeEngine.comparator_factory"><tt class="xref py py-attr docutils literal"><span class="pre">TypeEngine.comparator_factory</span></tt></a>.</p>
<p>The public base class for <a class="reference internal" href="#sqlalchemy.types.TypeEngine.Comparator" title="sqlalchemy.types.TypeEngine.Comparator"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine.Comparator</span></tt></a>
is <a class="reference internal" href="expression_api.html#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a>.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeEngine.__init__">
<tt class="descclassname">TypeEngine.</tt><tt class="descname">__init__</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeEngine.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Support implementations that were passing arguments</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeEngine.adapt">
<tt class="descclassname">TypeEngine.</tt><tt class="descname">adapt</tt><big>(</big><em>cls</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeEngine.adapt" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce an &#8220;adapted&#8221; form of this type, given an &#8220;impl&#8221; class
to work with.</p>
<p>This method is used internally to associate generic
types with &#8220;implementation&#8221; types that are specific to a particular
dialect.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeEngine.bind_expression">
<tt class="descclassname">TypeEngine.</tt><tt class="descname">bind_expression</tt><big>(</big><em>bindvalue</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeEngine.bind_expression" title="Permalink to this definition">¶</a></dt>
<dd><p>&#8220;Given a bind value (i.e. a <a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.BindParameter" title="sqlalchemy.sql.expression.BindParameter"><tt class="xref py py-class docutils literal"><span class="pre">BindParameter</span></tt></a> instance),
return a SQL expression in its place.</p>
<p>This is typically a SQL function that wraps the existing bound
parameter within the statement.  It is used for special data types
that require literals being wrapped in some special database function
in order to coerce an application-level value into a database-specific
format.  It is the SQL analogue of the
<a class="reference internal" href="#sqlalchemy.types.TypeEngine.bind_processor" title="sqlalchemy.types.TypeEngine.bind_processor"><tt class="xref py py-meth docutils literal"><span class="pre">TypeEngine.bind_processor()</span></tt></a> method.</p>
<p>The method is evaluated at statement compile time, as opposed
to statement construction time.</p>
<p>Note that this method, when implemented, should always return
the exact same structure, without any conditional logic, as it
may be used in an executemany() call against an arbitrary number
of bound parameter sets.</p>
<p>See also:</p>
<p><a class="reference internal" href="#types-sql-value-processing"><em>Applying SQL-level Bind/Result Processing</em></a></p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeEngine.bind_processor">
<tt class="descclassname">TypeEngine.</tt><tt class="descname">bind_processor</tt><big>(</big><em>dialect</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeEngine.bind_processor" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a conversion function for processing bind values.</p>
<p>Returns a callable which will receive a bind parameter value
as the sole positional argument and will return a value to
send to the DB-API.</p>
<p>If processing is not necessary, the method should return <tt class="docutils literal"><span class="pre">None</span></tt>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>dialect</strong> &#8211; Dialect instance in use.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeEngine.coerce_compared_value">
<tt class="descclassname">TypeEngine.</tt><tt class="descname">coerce_compared_value</tt><big>(</big><em>op</em>, <em>value</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeEngine.coerce_compared_value" title="Permalink to this definition">¶</a></dt>
<dd><p>Suggest a type for a &#8216;coerced&#8217; Python value in an expression.</p>
<p>Given an operator and value, gives the type a chance
to return a type which the value should be coerced into.</p>
<p>The default behavior here is conservative; if the right-hand
side is already coerced into a SQL type based on its
Python type, it is usually left alone.</p>
<p>End-user functionality extension here should generally be via
<a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">TypeDecorator</span></tt></a>, which provides more liberal behavior in that
it defaults to coercing the other side of the expression into this
type, thus applying special Python conversions above and beyond those
needed by the DBAPI to both ides. It also provides the public method
<a class="reference internal" href="#sqlalchemy.types.TypeDecorator.coerce_compared_value" title="sqlalchemy.types.TypeDecorator.coerce_compared_value"><tt class="xref py py-meth docutils literal"><span class="pre">TypeDecorator.coerce_compared_value()</span></tt></a> which is intended for
end-user customization of this behavior.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeEngine.column_expression">
<tt class="descclassname">TypeEngine.</tt><tt class="descname">column_expression</tt><big>(</big><em>colexpr</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeEngine.column_expression" title="Permalink to this definition">¶</a></dt>
<dd><p>Given a SELECT column expression, return a wrapping SQL expression.</p>
<p>This is typically a SQL function that wraps a column expression
as rendered in the columns clause of a SELECT statement.
It is used for special data types that require
columns to be wrapped in some special database function in order
to coerce the value before being sent back to the application.
It is the SQL analogue of the <a class="reference internal" href="#sqlalchemy.types.TypeEngine.result_processor" title="sqlalchemy.types.TypeEngine.result_processor"><tt class="xref py py-meth docutils literal"><span class="pre">TypeEngine.result_processor()</span></tt></a>
method.</p>
<p>The method is evaluated at statement compile time, as opposed
to statement construction time.</p>
<p>See also:</p>
<p><a class="reference internal" href="#types-sql-value-processing"><em>Applying SQL-level Bind/Result Processing</em></a></p>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.types.TypeEngine.comparator_factory">
<tt class="descclassname">TypeEngine.</tt><tt class="descname">comparator_factory</tt><a class="headerlink" href="#sqlalchemy.types.TypeEngine.comparator_factory" title="Permalink to this definition">¶</a></dt>
<dd><p>A <a class="reference internal" href="#sqlalchemy.types.TypeEngine.Comparator" title="sqlalchemy.types.TypeEngine.Comparator"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine.Comparator</span></tt></a> class which will apply
to operations performed by owning <a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a> objects.</p>
<p>The <a class="reference internal" href="#sqlalchemy.types.TypeEngine.comparator_factory" title="sqlalchemy.types.TypeEngine.comparator_factory"><tt class="xref py py-attr docutils literal"><span class="pre">comparator_factory</span></tt></a> attribute is a hook consulted by
the core expression system when column and SQL expression operations
are performed.   When a <a class="reference internal" href="#sqlalchemy.types.TypeEngine.Comparator" title="sqlalchemy.types.TypeEngine.Comparator"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine.Comparator</span></tt></a> class is
associated with this attribute, it allows custom re-definition of
all existing operators, as well as definition of new operators.
Existing operators include those provided by Python operator overloading
such as <a class="reference internal" href="expression_api.html#sqlalchemy.sql.operators.ColumnOperators.__add__" title="sqlalchemy.sql.operators.ColumnOperators.__add__"><tt class="xref py py-meth docutils literal"><span class="pre">operators.ColumnOperators.__add__()</span></tt></a> and
<a class="reference internal" href="expression_api.html#sqlalchemy.sql.operators.ColumnOperators.__eq__" title="sqlalchemy.sql.operators.ColumnOperators.__eq__"><tt class="xref py py-meth docutils literal"><span class="pre">operators.ColumnOperators.__eq__()</span></tt></a>,
those provided as standard
attributes of <a class="reference internal" href="expression_api.html#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">operators.ColumnOperators</span></tt></a> such as
<a class="reference internal" href="expression_api.html#sqlalchemy.sql.operators.ColumnOperators.like" title="sqlalchemy.sql.operators.ColumnOperators.like"><tt class="xref py py-meth docutils literal"><span class="pre">operators.ColumnOperators.like()</span></tt></a>
and <a class="reference internal" href="expression_api.html#sqlalchemy.sql.operators.ColumnOperators.in_" title="sqlalchemy.sql.operators.ColumnOperators.in_"><tt class="xref py py-meth docutils literal"><span class="pre">operators.ColumnOperators.in_()</span></tt></a>.</p>
<p>Rudimentary usage of this hook is allowed through simple subclassing
of existing types, or alternatively by using <a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">TypeDecorator</span></tt></a>.
See the documentation section <a class="reference internal" href="#types-operators"><em>Redefining and Creating New Operators</em></a> for examples.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.8: </span>The expression system was enhanced to support
customization of operators on a per-type level.</p>
<p>alias of <a class="reference internal" href="#sqlalchemy.types.TypeEngine.Comparator" title="sqlalchemy.types.TypeEngine.Comparator"><tt class="xref py py-class docutils literal"><span class="pre">Comparator</span></tt></a></p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeEngine.compare_values">
<tt class="descclassname">TypeEngine.</tt><tt class="descname">compare_values</tt><big>(</big><em>x</em>, <em>y</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeEngine.compare_values" title="Permalink to this definition">¶</a></dt>
<dd><p>Compare two values for equality.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeEngine.compile">
<tt class="descclassname">TypeEngine.</tt><tt class="descname">compile</tt><big>(</big><em>dialect=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeEngine.compile" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a string-compiled form of this <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a>.</p>
<p>When called with no arguments, uses a &#8220;default&#8221; dialect
to produce a string result.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>dialect</strong> &#8211; a <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Dialect" title="sqlalchemy.engine.interfaces.Dialect"><tt class="xref py py-class docutils literal"><span class="pre">Dialect</span></tt></a> instance.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeEngine.dialect_impl">
<tt class="descclassname">TypeEngine.</tt><tt class="descname">dialect_impl</tt><big>(</big><em>dialect</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeEngine.dialect_impl" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a dialect-specific implementation for this
<a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a>.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeEngine.get_dbapi_type">
<tt class="descclassname">TypeEngine.</tt><tt class="descname">get_dbapi_type</tt><big>(</big><em>dbapi</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeEngine.get_dbapi_type" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the corresponding type object from the underlying DB-API, if
any.</p>
<p>This can be useful for calling <tt class="docutils literal"><span class="pre">setinputsizes()</span></tt>, for example.</p>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.types.TypeEngine.hashable">
<tt class="descclassname">TypeEngine.</tt><tt class="descname">hashable</tt><em class="property"> = True</em><a class="headerlink" href="#sqlalchemy.types.TypeEngine.hashable" title="Permalink to this definition">¶</a></dt>
<dd><p>Flag, if False, means values from this type aren&#8217;t hashable.</p>
<p>Used by the ORM when uniquing result lists.</p>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.types.TypeEngine.python_type">
<tt class="descclassname">TypeEngine.</tt><tt class="descname">python_type</tt><a class="headerlink" href="#sqlalchemy.types.TypeEngine.python_type" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the Python type object expected to be returned
by instances of this type, if known.</p>
<p>Basically, for those types which enforce a return type,
or are known across the board to do such for all common
DBAPIs (like <tt class="docutils literal"><span class="pre">int</span></tt> for example), will return that type.</p>
<p>If a return type is not defined, raises
<tt class="docutils literal"><span class="pre">NotImplementedError</span></tt>.</p>
<p>Note that any type also accommodates NULL in SQL which
means you can also get back <tt class="docutils literal"><span class="pre">None</span></tt> from any type
in practice.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeEngine.result_processor">
<tt class="descclassname">TypeEngine.</tt><tt class="descname">result_processor</tt><big>(</big><em>dialect</em>, <em>coltype</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeEngine.result_processor" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a conversion function for processing result row values.</p>
<p>Returns a callable which will receive a result row column
value as the sole positional argument and will return a value
to return to the user.</p>
<p>If processing is not necessary, the method should return <tt class="docutils literal"><span class="pre">None</span></tt>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>dialect</strong> &#8211; Dialect instance in use.</li>
<li><strong>coltype</strong> &#8211; DBAPI coltype argument received in cursor.description.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.TypeEngine.with_variant">
<tt class="descclassname">TypeEngine.</tt><tt class="descname">with_variant</tt><big>(</big><em>type_</em>, <em>dialect_name</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.TypeEngine.with_variant" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a new type object that will utilize the given
type when applied to the dialect of the given name.</p>
<p>e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.types</span> <span class="kn">import</span> <span class="n">String</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.dialects</span> <span class="kn">import</span> <span class="n">mysql</span>

<span class="n">s</span> <span class="o">=</span> <span class="n">String</span><span class="p">()</span>

<span class="n">s</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">with_variant</span><span class="p">(</span><span class="n">mysql</span><span class="o">.</span><span class="n">VARCHAR</span><span class="p">(</span><span class="n">collation</span><span class="o">=</span><span class="s">&#39;foo&#39;</span><span class="p">),</span> <span class="s">&#39;mysql&#39;</span><span class="p">)</span></pre></div>
</div>
<p>The construction of <a class="reference internal" href="#sqlalchemy.types.TypeEngine.with_variant" title="sqlalchemy.types.TypeEngine.with_variant"><tt class="xref py py-meth docutils literal"><span class="pre">TypeEngine.with_variant()</span></tt></a> is always
from the &#8220;fallback&#8221; type to that which is dialect specific.
The returned type is an instance of <a class="reference internal" href="#sqlalchemy.types.Variant" title="sqlalchemy.types.Variant"><tt class="xref py py-class docutils literal"><span class="pre">Variant</span></tt></a>, which
itself provides a <a class="reference internal" href="#sqlalchemy.types.Variant.with_variant" title="sqlalchemy.types.Variant.with_variant"><tt class="xref py py-meth docutils literal"><span class="pre">with_variant()</span></tt></a>
that can be called repeatedly.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>type</strong> &#8211; a <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a> that will be selected
as a variant from the originating type, when a dialect
of the given name is in use.</li>
<li><strong>dialect_name</strong> &#8211; base name of the dialect which uses
this type. (i.e. <tt class="docutils literal"><span class="pre">'postgresql'</span></tt>, <tt class="docutils literal"><span class="pre">'mysql'</span></tt>, etc.)</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p class="versionadded">
<span class="versionmodified">New in version 0.7.2.</span></p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.Concatenable">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">Concatenable</tt><a class="headerlink" href="#sqlalchemy.types.Concatenable" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></p>
<p>A mixin that marks a type as supporting &#8216;concatenation&#8217;,
typically strings.</p>
<dl class="attribute">
<dt id="sqlalchemy.types.Concatenable.__init__">
<tt class="descname">__init__</tt><a class="headerlink" href="#sqlalchemy.types.Concatenable.__init__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <tt class="xref py py-attr docutils literal"><span class="pre">__init__</span></tt> <em>attribute of</em> <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></div>
<p>x.__init__(...) initializes x; see help(type(x)) for signature</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.NullType">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">NullType</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.NullType" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.TypeEngine</span></tt></a></p>
<p>An unknown type.</p>
<p>NullTypes will stand in if <tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt> reflection
encounters a column data type unknown to SQLAlchemy.  The
resulting columns are nearly fully usable: the DB-API adapter will
handle all translation to and from the database data type.</p>
<p>NullType does not have sufficient information to particpate in a
<tt class="docutils literal"><span class="pre">CREATE</span> <span class="pre">TABLE</span></tt> statement and will raise an exception if
encountered during a <tt class="xref py py-meth docutils literal"><span class="pre">create()</span></tt> operation.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.types.Variant">
<em class="property">class </em><tt class="descclassname">sqlalchemy.types.</tt><tt class="descname">Variant</tt><big>(</big><em>base</em>, <em>mapping</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.Variant" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.types.TypeDecorator" title="sqlalchemy.types.TypeDecorator"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.types.TypeDecorator</span></tt></a></p>
<p>A wrapping type that selects among a variety of
implementations based on dialect in use.</p>
<p>The <a class="reference internal" href="#sqlalchemy.types.Variant" title="sqlalchemy.types.Variant"><tt class="xref py py-class docutils literal"><span class="pre">Variant</span></tt></a> type is typically constructed
using the <a class="reference internal" href="#sqlalchemy.types.TypeEngine.with_variant" title="sqlalchemy.types.TypeEngine.with_variant"><tt class="xref py py-meth docutils literal"><span class="pre">TypeEngine.with_variant()</span></tt></a> method.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.7.2.</span></p>
<dl class="method">
<dt id="sqlalchemy.types.Variant.with_variant">
<tt class="descname">with_variant</tt><big>(</big><em>type_</em>, <em>dialect_name</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.Variant.with_variant" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a new <a class="reference internal" href="#sqlalchemy.types.Variant" title="sqlalchemy.types.Variant"><tt class="xref py py-class docutils literal"><span class="pre">Variant</span></tt></a> which adds the given
type + dialect name to the mapping, in addition to the
mapping present in this <a class="reference internal" href="#sqlalchemy.types.Variant" title="sqlalchemy.types.Variant"><tt class="xref py py-class docutils literal"><span class="pre">Variant</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>type</strong> &#8211; a <a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a> that will be selected
as a variant from the originating type, when a dialect
of the given name is in use.</li>
<li><strong>dialect_name</strong> &#8211; base name of the dialect which uses
this type. (i.e. <tt class="docutils literal"><span class="pre">'postgresql'</span></tt>, <tt class="docutils literal"><span class="pre">'mysql'</span></tt>, etc.)</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.types.Variant.__init__">
<tt class="descname">__init__</tt><big>(</big><em>base</em>, <em>mapping</em><big>)</big><a class="headerlink" href="#sqlalchemy.types.Variant.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a new <a class="reference internal" href="#sqlalchemy.types.Variant" title="sqlalchemy.types.Variant"><tt class="xref py py-class docutils literal"><span class="pre">Variant</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>base</strong> &#8211; the base &#8216;fallback&#8217; type</li>
<li><strong>mapping</strong> &#8211; dictionary of string dialect names to
<a class="reference internal" href="#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a> instances.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

</dd></dl>

</div>
</div>

    </div>

</div>

<div id="docs-bottom-navigation" class="docs-navigation-links">
        Previous:
        <a href="schema.html" title="previous chapter">Schema Definition Language</a>
        Next:
        <a href="event.html" title="next chapter">Events</a>

    <div id="docs-copyright">
        &copy; <a href="../copyright.html">Copyright</a> 2007-2013, the SQLAlchemy authors and contributors.
        Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
    </div>
</div>

</div>

        
    </body>
</html>


